Scoop -- the swiss army chainsaw of content management
Front Page · Everything · News · Code · Help! · Wishlist · Project · Scoop Sites · Dev Notes · Latest CVS changes · Development Activities
the new Scoop Admin Guide Docs
By janra , Section Project []
Posted on Wed Jan 21, 2004 at 12:00:00 PM PST
All of the administrative and feature setup sections are complete. The only section that is still incomplete is the "Extending Scoop" (aka "hacking") section. There's even a FAQ, and despite the fact that I'm calling it "done" with the rest of the guide, it can always use more questions that are likely to be asked. The Admin Guide is in the top menu over there ---->

Full var (Site Control) descriptions are in CVS already, and block descriptions (with descriptions of every special key the code recognizes for each block) should be appearing in CVS shortly.

Everybody: please feel free to offer suggestions or point out something that doesn't make sense to you. I have tested setting up and running every single feature I documented in the guide - admittedly on a test site with almost no content, but I did get them to successfully work. The documentation covers the latest 1.0-pre cvs code. If you are using an older version of Scoop, you won't be able to find some of the features described, and other features will work differently.

For those who have been wanting updated "scoop hacking" instructions, please take a look at the working version of the admin guide and let me know if there are any sections you would like to see added, details you don't want me to forget to cover, or details I seem to have forgotten in a section that seems otherwise finished. Offers of help are appreciated, but don't feel you need to write something - a quick note on a missing detail is also a great help!

I've submitted both the HTML and LaTeX source for the admin guide to panner for inclusion in the doc/ directory in cvs.

Oh, and to everybody who adds vars or blocks when making new features - can you either make the description as complete as the ones I've done, or at the very least tell me so I can write up a description? The very terse descriptions that were common before mostly only made sense to somebody who already knew what the block or var was for, and they didn't need the description much...

< Getting parameters in 'story_summary' | Scoop Bugtracking >

Menu
· create account
· faq
· search
· report bugs
· Scoop Administrators Guide
· Scoop Box Exchange

Login
Make a new account
Username:
Password:

Related Links
· Scoop
· Admin Guide
· working version
· More on Docs
· Also by janra

Story Views
  36 Scoop users have viewed this story.

Display: Sort:
the new Scoop Admin Guide | 17 comments (17 topical, 0 hidden)
Looks good (none / 0) (#1)
by phill on Tue Jan 27, 2004 at 02:37:57 AM PST

I'm looking forward to a more detailed hacking section though. I hate going through the code to figure out how some feature works or if it even exists so I can rev-engineer it to do something completely peverted.

-p



looks good (none / 0) (#3)
by coryking on Thu Jan 29, 2004 at 12:35:48 PM PST

First off - sweet! It's about time there are some good, complete docs for scoop!

Couple of things, some of which I could help with.

  • The the page-to-page navigation needs to be improved. I've been thinking about this a bit (I'm taking a course on this very subject right now) and have a few ideas on improving it.
  • Use a san-serif font like arial or helvetica for the text type. San-serif is much easier to read onscreen then serif'd fonts. Serifs are hard to render onscreen thanks to the low resolution of monitors and thus make the characters less easy to recognize, slowing your reading down by like 10% -> 20%.*
  • Get rid of the numbering on section headers. That kind of stuff is pretty irrelivant to online stuff and makes scaning for a particular section harder. The best example I have of section numbering gone bad is the PHP docs which insist on using roman numbering and make it really hard to scan.
  • We could also probably do a re-ordering of the outline. Anything more then about 7 section headings suggests a re-order. Our memory can only hold so much information, and some of these lists are quite large (21 headings under "features and customization"). This makes it hard to scan and find what you are looking for.

    For example "comments & views", "trusted users & mojo" seem like one group, "story selection", "archiving", "digest emails", "user diaries" are another. Perhaps we move to a more task-oriented heiarchy like "Handling Comments", "Handling Stories", etc. The PHP guys could probably take this tip too.

  • Lastly, I could probably do some editing for you in my spare time. Ve Shalt Zee. I might be able to use the design of this documentation for a class project. Features would then include good looking navigation and other things that would make it look nice and professional. Plus I could get credit for it :-)
* T. Williams - Guidelines for Designing and Evaluating the Display of Information on the Web. Technical Communication, Volume 47, No.3, p.383-396 August 2000

--
Cory R. King
xlan.org (scoop hosting)
photographica (pictures)



more questions (none / 0) (#6)
by coryking on Sat Feb 07, 2004 at 07:47:48 PM PST

I'm axious to work on this document, but I have a few questions.

  • How do I get the "source" for this document?
  • I have *no* clue how to use LaTEX or even really what the hell it is. Can I just edit this puppy in word and then somehow magically make it LaTEX (which then does what?)
  • Can I then take this LaTEX thingy and put it into dreamweaver, or somehow use an HTML page as a stylesheet for LaTEX?
  • Is LaTEX even a good choice for this document? Do most scoop programmers know it? It it ideal for a document that will be used on the great InterWeb but probably never wind up on a dead tree? Can we do something simpler like make a template in Dreamweaver and pour the content into that? In that case, all the headings would be simple HTML tags that would then get their formatting from a CSS file.

Actually, the most important question is, how do we edit this online? I have a lot of feedback that I'd like to give, but have no way of actually doing so. If it was a word document, we could use the track changes. I have no clue how to edit a LaTEX document, or even if such tools exist.

--
Cory R. King
xlan.org (scoop hosting)
photographica (pictures)



the new Scoop Admin Guide | 17 comments (17 topical, 0 hidden)
Display: Sort:

Hosted by ScoopHost.com Powered by Scoop
All trademarks and copyrights on this page are owned by their respective companies. Comments are owned by the Poster. The Rest © 1999 The Management

create account | faq | search