GNOME.org
 

Re: Gnumeric Documentation styleguide

yum 1.0.0!



I am not thrilled by this guide. It does not seem to make life easier
for anyone: documenters or readers. Fighting the docs has persuaded me
that a good guide is needed but a good guide is a much more developed
document than this is. My feeling is also that this is not gnumeric
specific but should be part of the gnome doc project. We need a good
guide with explanations to speed up life for everyone. When I have time,
I'll visit this through the gnome doc project rather than through
gnumeric.


On Wed, 2002-01-02 at 09:53, Kevin Breit wrote:

    However, once this
    styleguide hits 1.0, it's too late.  Basically a "speak now or
    forever hold your peace" action.


This, I am afraid, is a misunderstanding of the nature of long term
projects. Being pedantic about the style guide is counter productive. A
good guide gives people good reasons to want to follow it and has made
good decsions.Consider, beyond the basic docs, is there any reson to
require the person who might write a section: "Advanced dervative
pricing models with Gnumeric" to use a particular theme for screenshots?
Better to have the section than to force someone to be compliant to
write this doc. A good guide is good because it's smart and a guide
because people want to follow it. 


So what are the best suggestions we can cobble together, and can we give
an ounce of explanation?


First of all we have to deal with editors. A documentation project
should be able to use any of a number of editors: emacs, xemacs, vim
even abiword makes docbooks stuff I believe. If we can get the gnome doc
project to assess different editors and get every common editor so
people can 
1) pull in files how they want
2) put out files in the common format
we will all be happier.
(As an example, open this styleguide in vim. I mean it. Open what you
have written, look around and think about the issues which come up. Even
responding in evo, I had to do a lot of extra work.)



Gnumeric Styleguide v0.1
by Kevin Breit (mrproper ximian com)

Purpose:
Gnumeric 1.0 came included with over 400 pages worth of documentation.  While generally complete in 
content, the documentation was unsatisfactory in regards to organization.  The organization made navigating 
the SGML files a challenge.  Gnumeric 1.2 is going to be a port to Gnome 2.0.  In this port, the 
documentation is going to require a port to XML.  While not a large effort, the port is generally a good 
time to reorganize, if not rewrite, the Gnumeric documentation.  For the documentation to be easy to 
navigate, the documentation needs to follow understood standards.  This document outlines the said 
standards to follow while writing the documentation.

Content:
This paper outlines the following items:
* Indenting
* File naming
* Section naming
* Tags
* Chapters
* Screenshots
* emacs goodies

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. 




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.

This is a GNOME doc project issue. It's harder than this. The user
should choose the <guimenu>File</guimenu>{space}menu to choose the
<guimenuitem>Open</guimenuitem> (where did <menuchoice> come from?)
which will open the <guilabel>Open<g/uilabel>(should be guidialog or
some such) dialog. This kind of markup could be helpful but I ended up
reverting to the "File" menu occaisonally because there are different
situations which arise in discussion.



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. Docbook left me
no way to amalgamate this chapter and still have this layout be quick
and easy for the reader.
Only one chapter should occur per file as 
well.
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 


emacs Goodies:
  This section is in no way a guideline on style.  This is a kind of...reward for reading through this, and 
hopefully following this.  It includes some nifty emacs tricks which I have learned.
  The first and foremost is nearly a requirement for you emacs users: psgml mode.  psgml mode is used for 
dealing with XML, SGML, and HTML.  It is very useful, and comes default with most distributions.  The 
following tips are dependent on psgml mode.  Once psgml mode is installed, you can activate it by adding 
the following to your .emacs file:

(setq sgml-indent-data t)
(autoload 'sgml-mode "psgml" "My Most Major Mode" t)
(setq sgml-mode-hook '(lambda () "Defaults for SGML mode."
(auto-fill-mode) (setq fill-column 70)))

  The following script finds the nearest ChangeLog file, prepends an entry to the top, and is ready for you 
to type your changes.  This is activated by typing M-n.

(defun changelog-entry ()
  "Add entry to ChangeLog"
  (interactive)
  (progn
    (if (equal (file-name-nondirectory (buffer-file-name)) "ChangeLog")
        (progn
          (basic-save-buffer)
          (kill-buffer "ChangeLog"))
      (progn
        (add-change-log-entry)))
;       (insert (current-time-string) "\n")))
))
(setq user-mail-address "youremail domain com")
(setq user-full-name "Your Name")

(global-set-key "\M-n" 'changelog-entry)

This will add the <figure> structure for you to your SGML file where the cursor is.  It will prompt for the 
title of the figure as well as the filename (no extension).  All the data will be generated for you.  This 
is used by hitting F7.


(defun gdp-insert-figure (title filename)
  (interactive "MTitle: \nMFilename (no extension): ")
  (let ((point (point)))
    (insert
     "<figure>
      <title>" title "</title>
<screenshot>
<screeninfo></screeninfo>
<graphic  format=\"png\" fileref=\"" filename "\" srccredit=\"Kevin Breit\">
</screenshot>
</figure>")
    (indent-region point (point) nil)
    (search-backward "</screeninfo>" point t)))
(define-key global-map [f7] 'gdp-insert-figure)

This will add the very common <listitem><para> tags on separate lines.  This is used by hitting F1:

(defun kevin-insert-listitem ()
  (interactive)
  (let ((point (point)))
    (insert
     "<listitem>
        <para>")
    (indent-region point (point) nil)))
(define-key global-map [f1] 'kevin-insert-listitem)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]