* OpenBMC userguide questions
@ 2020-05-15 6:49 Zbyszek
2020-05-15 12:13 ` Patrick Williams
0 siblings, 1 reply; 3+ messages in thread
From: Zbyszek @ 2020-05-15 6:49 UTC (permalink / raw)
To: openbmc; +Cc: bradleyb, patrick, anoo, andrew, gmills
Hi,
Few days ago I have pushed to review something that can be called a userguide.
https://gerrit.openbmc-project.xyz/c/openbmc/docs/+/32234
Because there were no user guides so far neither any template some
questions arose, like:
* Should we use the reply markup to indicate side comments though-out?
* 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.
* Do we allow the `---` line separating doc header and text
introducing to document?
I will appreciate you answers here on mailing list or as a comments
under mentioned review.
Thanks,
Best regards,
-Zbigniew
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: OpenBMC userguide questions
2020-05-15 6:49 OpenBMC userguide questions Zbyszek
@ 2020-05-15 12:13 ` Patrick Williams
2020-05-18 7:15 ` Zbyszek
0 siblings, 1 reply; 3+ messages in thread
From: Patrick Williams @ 2020-05-15 12:13 UTC (permalink / raw)
To: Zbyszek; +Cc: openbmc, bradleyb, anoo, andrew, gmills
[-- Attachment #1: Type: text/plain, Size: 1318 bytes --]
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
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: OpenBMC userguide questions
2020-05-15 12:13 ` Patrick Williams
@ 2020-05-18 7:15 ` Zbyszek
0 siblings, 0 replies; 3+ messages in thread
From: Zbyszek @ 2020-05-18 7:15 UTC (permalink / raw)
To: Patrick Williams; +Cc: openbmc, bradleyb, anoo, andrew, gmills
Thank you Patrick for your quick response.
I will apply your comments in the document.
pt., 15 maj 2020 o 14:13 Patrick Williams <patrick@stwcx.xyz> napisał(a):
>
> 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
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-05-18 7:16 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-05-15 6:49 OpenBMC userguide questions Zbyszek
2020-05-15 12:13 ` Patrick Williams
2020-05-18 7:15 ` Zbyszek
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.