Re: Gnumeric Documentation styleguide

[Kevin Breit <mrproper ximian com>]

On Wed, 2002-01-02 at 12:01, Adrian Custer wrote:

    > Indenting:
    >   Indenting is a very contraversial topic among most programmers.  I have found my favorite styles and 
found most people use the same way.
    >   Indenting will use 2 spaces.  
    
    This should be a non-issue. The fact that it remains an issue is, I
    believe due to emacs broken-ness. Indenting should be done with tabs,
    and users allowed to set how big they want their tabstops. The files
    themselves should have tab characters for indentation. However, I have
    no idea how to make emacs use tabs instead of spaces. I know it can read
    them, I don't know if it can ouput them. 
    
Ideally, yes, I agree.  However, I _hate_ 8 spaces (or one tab, same
thing) for indenting.  For C, that is good.  For XML/HTML/SGML that is
bad.  *ML tends to have very nested structures of tags.  If you do 8
spaces, before long, you're going to start lines at character 75 out of
80.  Please comment.
    
    > File Naming:
    >   Files should all end with .sgml.  
    
    They should also be an annotated version of the chapter title. 
    what's annotated mean in this context? How about.
    
    The file name should be named for easy recognition in the following way:
    
        type-chaptername-subsectionname.sgml
    
    if you want the "type" give writers an good sized list with concrete
    examples of what is and what is not in that.
    "usage" could be anything since it's a manual on how to use gnumeric.
    
     All files should also be prefixed with the type of file they are.  
    For example, a file describing how to do basic navigating of the Gnumeric 
    interface would be a "usage" file.  This would be named usage-navigation.sgml.  
    If a file grows to be too large for one file, it can be changed to be two 
    or more files.  These should associate by name to the parent file.  If the 
    previous example had a section about using the keyboard, the file would be 
    called: usage-navigation-kbd.sgml.  Filenames are hyphen delimited. 
    
    > 
    > Section Naming:
    >   Sections should be both an abbrivated version of their title 
    as well as their parent section.  
    abbreviations are not helpful since I have no guarantee that we agree on
    the abbreviation. I would have to open your section and find the id to
    be able to be sure that my ref will match your abbrv. :-) I suggest full
    names--a bit more typing but saves time overall.
    
    These are hypen-delimited.  all lower case. in order:
    chapter-section-???
    
    
    An author should be able to open up a section in an SGML section title 
    and be able to identify the parent sections.  For example:
    > 
    > <sect1 id="intro">
    >   <title>Introduction</title>
    >   <para>
    >     ...
    >   </para>
    >   <sect2 id="intro-whatis">
    {How do I know this id is going to be whatis and not what-is or
    whatisgnumeric? We need clear rules.}
    >     <title>What is Gnumeric?</title>
    >     <para>
    >       ...
    >     </para>
    >   </sect2>
    > </sect1>
    > 
    Cross-referencing:
    we need a clear policy on this so I can be reading the docs in html,
    find the section I want to link against and know what the id should be.
    
    
    
    
    > Tags:
    >   Tags should be used promiscuously in the documentation, even when 
    formatting is not changed due to the tag.  All application names should be 
    wrapped in the <application> tag, menus should be wrapped in <menuchoice>, 
    and so on.
    
In regards to the tag issue which you voiced concern about.  Yes, this
is a GDP issue.  And it is an issue they have taken authority on.  It is
still only sometimes practiced.  I am reiterating it here for emphasis.

    > 
    > Chapters:
    >   Chapters should be defined in the file which encompasses with them.  The 
    entity for the chapter will of course be defined in the gnumeric.sgml file.  
    The <chapter> tag will be issued in the chapter files.  This will help to make 
    associating files to content easier for new writers.  
    
    Number of chapters should 
    be kept to a reasonable minimum.  
    This is questionable. Since docbook only gives us a very small number of
    subsectioning before subesections no longer occur on their own html
    page. Semantically I would like to have done all of chapters
    gui-elements, menus, toolbars, worksheet in one chapter. 

You couldn't do a:
<chapter id="ui-overview">
  <sect1 id="ui-overview-gui-elements">
  ...
  <sect1 id="ui-overview-menus">
    <sect2 id="ui-overview-menus-file">
  
Even the deepest of menus should get you to a <sect5>.

    Only one chapter should occur per file as 
    well.

Please take a look at:

http://cvs.gnome.org/lxr/source/evolution/help/C/usage-mail.sgml
and
http://cvs.gnome.org/lxr/source/evolution/help/C/usage-mail-org.sgml

This is stuff from the Evolution manual.  Aaron and I initially had it
as one file.  Suddenly we noticed that the file was approaching 3000
lines.  While we could have kept it as one file, it soon became _very_
hard to manage.  Eventually, we made -org its own chapter, but that's
besides the point.

    I would restate this to be. One file cannot cover more than one chapter.
    
    > 
    > Screenshots:
    >   Screenshots will follow the GDP's guidelines for screenshots. For up to date information on 
screenshot requirements, please see the GDP guidelines on CVS:
    > /cvs/gnome-docu/gdp/style/screenshots.sgml
    For the introductory chapters, this may be critical. Once you are
    thinking about statistical models in gnumeric, you know how to use the
    app and you probably have a pretty good idea that things can look
    different. I think the documenter's time trumps standardization here. A
    simple statement (your outer frame may look different) and internal
    consistency to the chapter are all I think is needed. I use default gtk
    layout and helix decorations. People now tell me that I don't. It's not
    really worth my time to change the layout to match some ideal unless
    someone can say: Hey your layout is confusing for this kind of reader.
    Then I get to choose how to deal with it.
    
    How about:
    Intro chapters must follow the gdp guidlines. Later chapters should if
    possible, if not they must:
    1) be consistent across the whole subject section
    2) be legible and easily comprehensible 

Why should later chapters be omitted?

Thanks for the input though.  I really appreciate it!

Kevin