Forum OpenACS Development: 4.6.x Documentation; Documentation formatting

1. Add an Upgrade section
2. Revision of the Unix/Linux section
3. Adding VMWare and Mac sections from contributors
4. Adding a tutorial (covering apm, creating tables that use acs_objects and stored procedures, integration with content_revisions, openfts, notifications, and general_comments; using ad_form and templates)

Questions:

1. The release notes on openacs.org are much bigger than the release notes in HEAD. I'm staring at the most recent version of release-notes.xml (1.5, by jeffd) and they're only ~90 lines. Where is the big, long set of release notes that's up on openacs.org?
2. Thumbs up or thumbs down to the more visually agressive style ? (compare New style and current style.

   Specifically,

   • shading and borders for GUI elements (e.g. Next button)
   • shading for text from the screen
   • differentiating between shell code and program listings
   • highlighting text (servername, password) that should be changed before it's typed in
   • eye-catching green on black for user shell input
3. Wherever we have shell input, I want to make sure that it can be cut and paste directly into a shell. This means removing the shell prompts, stdout responses, and comments. Stripped shell commands, however, are bad for readability and learning. Here are some different ways to accomplish it:
   • Fancy html tricks so that commentary doesn't get copied. Easier to maintain. Unreliable in use.
   • Duplicate code in place - two columns, or two rows. One readable, one copyable. Could get bulky and confusing.
   • Duplicate code in a separate place. Footnotes to link the inline readable code to a file of copyable code. Possibly hard to follow and harder to maintain.
4. Does anybody object if I put extensions into the css file - not changing any defaults or current settings, but adding new classes to support more formatting?
5. FYI - I'm working from HEAD and targeting 4.6.1/4.6.2.

Those sound like really useful additions indeed!

To comment on your questions:

2) Personally, I think I prefer the current style (probably mostly because I've grown acustomed to it). I find the new style a little muddled 😊

3) Hmm.. I can see your point that cutting/pasting should be easy. However, I think we ought to focus on readability, and keeping the prompts makes it much easier for the installer to realize from where and as which user a certain command should be issued. The "first-timer" is probably more anxious about gaining understanding of what's going on during the installation than (s)he is about gaining time.

4) I don't think anyone will object to this.

I am a big fan of cut and paste things as well. One example of something we might consider is the oracle setup statements page that Lars did. I use it all the time...

Terrific work you've been doing.

I don't think a tutorial should be part of the Installation documents, because, well, it's not necessary for installation. If you already have OpenACS installed (say, from your distribution's install process, it may happen in the future), how would you know there's a tutorial in the installation docs?

The new style, while adding some enhancements, is too muddled for me. Too many colors, button-looking things that are not buttons, bright green on black text that looks like my ancient PC XT terminal.

I especially dislike the huge screens where you just have a long stream of commands for which the user is given no clue what they are for. Is the user supposed to just trust us? Or we could educate the user and let him/her know why we are suggesting him/her to run the next few commands?

For question 1, the longer release notes are only on openacs.org. I posted about it on a thread a while ago. OpenACS 4.6 was released without much fanfare, and wrote the longer release notes after the fact, so I couldn't just add to the Docbook sources and regenerate.

For question 3, cut-and-pasting is good, but I would personally never copy and paste more than a couple lines. In the example you posted, you have a screen full of commands. One can't tell where one set of commands ends and the other starts, and why they are being run.

So if the screens for command copy-and-pasting are short and explained, then we should be ok.

-Roberto

That seems to be the ideal way to do it, if it's possible to do in docbook and is cross platform compatible.

Those are big ifs, though. Have you looked into it yet?

Also, the green on black is not that readeable, actually, yellow on black, or black on yellow, are supposed to be the most striking combinations and it's why many street signs utilize the scheme. But that combo is garish as well.

How about hot pink on mauve?

talli

The new style is hideously awful, IMNSHO. All the big ugly button looking things are confusing. That's definitely the strong first impression, anyway! :) Overall, way too much chartjunk. Some of the other changes have merit, though.

Also, I suspect that numbering the steps may actually be counterproductive. These steps are not at all written in stone, and as the document changes all those numbers are going to change. Do we really want people to start referring to "problem in step 19" when the number 19 may well change the next time someone edits the document? On the other hand, for a given revision of the document, being able to refer to steps by numbers is kind of nice.

The attempt highlight the nouns in long lists of instructions like "check Editors", "uncheck Web Server" seems like a good idea, but the strong dark gray color isn't the best choice for this. Light gray should do the trick.

Also, I hope all the special markup is being done with some kind of stylesheet so e.g. the "draw attention to this text" background color can be easily tweaked?

In the old style, I also don't like the dark gray backgrounds very much. Too visually jarring. Backgrounds around all the shell commands are fine, but I'd suggest a much lighter gray color.

• Minimize the change from the current style
• Keep the style non-aggressive
• Material for copy-paste must be fully visible before copying so people can see what's in it.

With that in mind, here is my first proposal for updated document style. This is all done in CSS, so it will be easy to continue adjusting. Please let me know if there's something in it that you can't stand, and if so please suggest an alternative. Thanks for the great feedback.

*) The 'guilabel' class is too low in contrast, making the button hard to read for people with poor eyesight. I would prefer a subtle variation of the programlisting class for readability, something like this:

.guilabel{background-color:#eeeeee; padding:2px; color:#0000dd;}

*) Konqueror v3.1.0 doesn't render the border on the guibutton class, but you can hardly be blamed for that. Makes the buttons look like normal links with a bold typeface. Looks as expected in Mozilla.

I'm itching to say that if you find yourself debugging something as simple as text formatting, you are overcomplicating things a bit somewhere.

Don't let me start how this is going to look in print from different browsers. Subtle features like fancy shading may well be gone on the printout, and color too. What's gauranteely left on the print is fixed width vs. variable width font, headers, and bold and italic attributes. I think, the old style could be used in print form well.

Please forgive me for only discussing problems. It's easier to critique others than to do something myself, you know :)

I would like to add a tutorial to the section, covering the existing topics and some new ones in a much briefer, more howto-oriented way. Here's my list:

• How to use the APM to start a new package
• How to write documentation, including self-documenting code
• How to set up the database tables and procedures for your new package, including:
  • How to create automated install/uninstall/upgrade scripts
  • How and when and why to use acs_objects
  • How to use stored procedures for __new, __delete, and __name stored procedures
  • How to use the content management tables
• How to make your package searchable with OpenFTS/Oracle
• How to make your package send email notifications
• How to use tcl/adp pairs to present pages, including
  • How to use ad_page_contract
  • How to use the template system
  • How to prepare pagelets for inclusion in other pages
• How and when to put procedures in a tcl procedure library
• How to add general_comments to your pages
• How to use a single ad_form to make a page that shows insert/edit forms, validates data, and does the database work. (plan to draw from Jon Griffin's doc)
• How to add automated regression testing to your packages
• How and when to implement caching
• How to isolate database code for portability
• How to use the html/text entry widget to get the "does this look right" confirm page

All of these should be in the context of one fairly simple package like the notes thing. Anyone who would like to tackle a section, or just send me notes to save me some time, or has more stuff they want to see on the list, please email.

1. How do I edit that page?
2. What's the best way to get community feedback on doc work in progress? I can keep posting one-offs on my site; I can check stuff into cvs and invite people to look at them through the cvs web interface (e.g., tutorial.html. (I can never find the cvs interface without searching - could this be linked from somewhere prominent like https://openacs.org/projects/openacs/?) A third way would be for me to maintain a HEAD or pre-checkin instance of the doc package on one of my servers. I'd like to post work-in-progress as soon as it's specific enough that people can see where I'm headed, and before I've gone too far in a direction that people disagree with.
3. My lists of planned work are ... mostly already detailed in this thread, actually. Here's current status:
   • Add an Upgrade section (already checked in to cvs)
   • Revise the Install Section to:
     • Include most current docs on non-linux installs (started, needs volunteers with those platforms)
     • Include a Reference Install (started; needs community feedback on what a Reference Install should be)
     • Integrate all the supporting software into the flow (not started)
     • Add a maintenance section (not started)
   • Rearrange the Developer Documentation: (in planning)
     • First, a hello world tutorial (like this but shorter)
     • Second, an extended tutorial with standalone sections for each of the topics detailed above
     • Third, the existing material, updated and cleaned up. The difference between the extended tutorial and the current developer's guide is that a tutorial is oriented for learning and the guide is more oriented towards reference. Where possible, I'd even like to consider moving material from the Developer's Guide to the per-package documentation.

http://sdm.openacs.org/new-file-storage/download/docs-status.html?version_id=471

We have also discussed several times (in #openacs) the revamping of the developer documents to include more tutorial-like things.

I think improving individual package documentation will go a long way towards making developing with OpenACS easier. This is especially true for new packages.

"No package left behind" could be our motto.

-Roberto

I don't like to complain. But I really think the visual style is very distracting. Is it really necessary to surround the word "Next" in a grey box, and underline the N in next? I think most people will get the point if you just say "click Next." I feel the same way about the dark grey background sections. It makes it much more difficult to read the text formatted this way.

My advice would be to use a monospaced style for user entered input and limit the amount of text that is displayed as bold.

I also want to thank you for taking on this task! It is greatly appreciated.

• All of the button and label markup is gone except for courier font
• shaded background is used in blocks to indicate shells and program listings
• The body font is a surprise. I've actually left it sans-serif through all versions but it's coming out serif anyway. Feedback welcome as I sort through browser settings, site-wide stylesheets, etc, to understand this phenomenon.
• Bold is used only for text that you enter into the computer, and in headings which are also in a larger font.
• I've left the "replaceable" text red, because it's also italic and a bit bigger than surrounding text, so it doesn't just rely on color. It's the only italic used.
• Shell commands are duplicated to make cut-paste easier.