OpenBMC userguide questions

[Patrick Williams]

Hi Zbyszek,

In general, I would say you should follow the format of existing
documents.  I think that answers the majoriy of your questions at a
high-level.

On Fri, May 15, 2020 at 08:49:49AM +0200, Zbyszek wrote:
> * Should we use the reply markup to indicate side comments though-out?

I would say no.  In Markdown ">" are for quotes.  You're not quoting
anything.  Skimming through it seems like with a little effort you could
just integrate these "side comments" into the document flow.

> * Do we want to add user level doc to userguide? or put this doc under
> security? Currently userguide only has a .tex including other markup.

It looks like the userguide directory is for a .tex wrapper that was put
in to generate a single document from a few Markdown sub-files.  The
majority of the "content" of this file comes from the root directory, so
it would seem that the pattern is to treat most things in root as
"user-guides".

The whole docs repository could use some reorganization, but we should
treat that separate from this commit.

> * Do we allow the `---` line separating doc header and text
> introducing to document?

No, let's follow the format of the existing documents.  Maybe a 
"## Introduction" would be just as appropriate in this case.

-- 
Patrick Williams
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.ozlabs.org/pipermail/openbmc/attachments/20200515/4b7d4f74/attachment.sig>