OpenBMC userguide questions

Patrick Williams patrick at
Fri May 15 22:13:43 AEST 2020

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

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

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: <>

More information about the openbmc mailing list