Re: [DOC] Example asciidoc file as guideline

[Vaibhav Jain]

Hi Michael,

+1

Vaibhav Jain
Sr. Enterprise Software Engineer
HotWax Systems
m: 782-834-1900 e: vaibhav.j...@hotwaxsystems.com


On Sun, Mar 18, 2018 at 10:26 PM Michael Brohl 
wrote:

> Maybe I was not clear enough... I am suggesting some kind of style guide.
>
> I think if we provide it in the early stage, people might get inspired
> from it and have examples in a very compressed form. I find the several
> examples that I've studied very helpful but they are cluttered all over
> the internet so it could be a shortcut for others.
>
> I will provide an example to make it clearer. Will take some days as I
> am off until coming Wednesday.
>
> Thanks,
>
> Michael Brohl
> ecomify GmbH
> www.ecomify.de
>
>
> Am 18.03.18 um 17:46 schrieb Taher Alkhateeb:
> > Hmmm, Sounds like a good idea, but perhaps maybe a bit early? We might
> > be still evolving and learning how to structure our documents.
> >
> > Also, maybe if we keep our documents clean and consistent, then they
> > themselves offer an example for how to write stuff? Examples usually
> > run out of date quickly unless we have some kind of mechanism in place
> > for always keeping them up to date. Anyway, if we decide to go that
> > route, [1] serves as a nice sample for us to imitate but with
> > instructions specific to OFBiz
> >
> > [1] https://asciidoctor.org/docs/asciidoc-recommended-practices/
> >
> > On Sun, Mar 18, 2018 at 7:35 PM, Michael Brohl 
> wrote:
> >> Heyho,
> >>
> >> I played around with asciidoc a bit and did some minor changes to
> display a
> >> nice title page and did some configurations for the user/developer
> manuals.
> >>
> >> I studied a few example .adoc files and wonder if we should provide a
> best
> >> practice example .adoc file. This could contain all formatting,
> guidelines
> >> to mark special contents (info, attention, citations etc.) or how to
> format
> >> code examples.
> >>
> >> It would be a guideline as well as an example to learn from. I am hoping
> >> that it is easier for people to get started and it could also improve
> the
> >> quality.
> >>
> >> This document itself could be in the codebase and evolve over time.
> >>
> >> What do you think?
> >>
> >> Regards,
> >>
> >> Michael Brohl
> >> ecomify GmbH
> >> www.ecomify.de
> >>
> >>
> >>
>
>
>

Re: [DOC] Example asciidoc file as guideline

[Jacques Le Roux]

Thanks Michael and Sharan.

Thank you also Taher for the files structure.

This is quite useful, I'll follow the way (by shamelessly copying on humanres 
doc)

Jacques


Le 19/03/2018 à 09:17, Sharan Foga a écrit :

Hi Michael

+1

A style guide is a great idea. I've started trying to capture some general 
stuff on the documentation wiki page about formatting etc, but it's not enough 
and needs work so an example document with all the styles we want to use would 
be good.

Thanks
Sharan

On 2018/03/18 18:44:29, Taher Alkhateeb  wrote:

Ahh I see, sounds cool. Looking forward

On Sun, Mar 18, 2018 at 7:55 PM, Michael Brohl  wrote:

Maybe I was not clear enough... I am suggesting some kind of style guide.

I think if we provide it in the early stage, people might get inspired from
it and have examples in a very compressed form. I find the several examples
that I've studied very helpful but they are cluttered all over the internet
so it could be a shortcut for others.

I will provide an example to make it clearer. Will take some days as I am
off until coming Wednesday.

Thanks,

Michael Brohl
ecomify GmbH
www.ecomify.de


Am 18.03.18 um 17:46 schrieb Taher Alkhateeb:


Hmmm, Sounds like a good idea, but perhaps maybe a bit early? We might
be still evolving and learning how to structure our documents.

Also, maybe if we keep our documents clean and consistent, then they
themselves offer an example for how to write stuff? Examples usually
run out of date quickly unless we have some kind of mechanism in place
for always keeping them up to date. Anyway, if we decide to go that
route, [1] serves as a nice sample for us to imitate but with
instructions specific to OFBiz

[1] https://asciidoctor.org/docs/asciidoc-recommended-practices/

On Sun, Mar 18, 2018 at 7:35 PM, Michael Brohl 
wrote:

Heyho,

I played around with asciidoc a bit and did some minor changes to display
a
nice title page and did some configurations for the user/developer
manuals.

I studied a few example .adoc files and wonder if we should provide a
best
practice example .adoc file. This could contain all formatting,
guidelines
to mark special contents (info, attention, citations etc.) or how to
format
code examples.

It would be a guideline as well as an example to learn from. I am hoping
that it is easier for people to get started and it could also improve the
quality.

This document itself could be in the codebase and evolve over time.

What do you think?

Regards,

Michael Brohl
ecomify GmbH
www.ecomify.de

Re: [DOC] Example asciidoc file as guideline

[Sharan Foga]

Hi Michael

+1 

A style guide is a great idea. I've started trying to capture some general 
stuff on the documentation wiki page about formatting etc, but it's not enough 
and needs work so an example document with all the styles we want to use would 
be good.

Thanks
Sharan

On 2018/03/18 18:44:29, Taher Alkhateeb  wrote: 
> Ahh I see, sounds cool. Looking forward
> 
> On Sun, Mar 18, 2018 at 7:55 PM, Michael Brohl  
> wrote:
> > Maybe I was not clear enough... I am suggesting some kind of style guide.
> >
> > I think if we provide it in the early stage, people might get inspired from
> > it and have examples in a very compressed form. I find the several examples
> > that I've studied very helpful but they are cluttered all over the internet
> > so it could be a shortcut for others.
> >
> > I will provide an example to make it clearer. Will take some days as I am
> > off until coming Wednesday.
> >
> > Thanks,
> >
> > Michael Brohl
> > ecomify GmbH
> > www.ecomify.de
> >
> >
> > Am 18.03.18 um 17:46 schrieb Taher Alkhateeb:
> >
> >> Hmmm, Sounds like a good idea, but perhaps maybe a bit early? We might
> >> be still evolving and learning how to structure our documents.
> >>
> >> Also, maybe if we keep our documents clean and consistent, then they
> >> themselves offer an example for how to write stuff? Examples usually
> >> run out of date quickly unless we have some kind of mechanism in place
> >> for always keeping them up to date. Anyway, if we decide to go that
> >> route, [1] serves as a nice sample for us to imitate but with
> >> instructions specific to OFBiz
> >>
> >> [1] https://asciidoctor.org/docs/asciidoc-recommended-practices/
> >>
> >> On Sun, Mar 18, 2018 at 7:35 PM, Michael Brohl 
> >> wrote:
> >>>
> >>> Heyho,
> >>>
> >>> I played around with asciidoc a bit and did some minor changes to display
> >>> a
> >>> nice title page and did some configurations for the user/developer
> >>> manuals.
> >>>
> >>> I studied a few example .adoc files and wonder if we should provide a
> >>> best
> >>> practice example .adoc file. This could contain all formatting,
> >>> guidelines
> >>> to mark special contents (info, attention, citations etc.) or how to
> >>> format
> >>> code examples.
> >>>
> >>> It would be a guideline as well as an example to learn from. I am hoping
> >>> that it is easier for people to get started and it could also improve the
> >>> quality.
> >>>
> >>> This document itself could be in the codebase and evolve over time.
> >>>
> >>> What do you think?
> >>>
> >>> Regards,
> >>>
> >>> Michael Brohl
> >>> ecomify GmbH
> >>> www.ecomify.de
> >>>
> >>>
> >>>
> >
> >
> 

Re: [DOC] Example asciidoc file as guideline

[Taher Alkhateeb]

Ahh I see, sounds cool. Looking forward

On Sun, Mar 18, 2018 at 7:55 PM, Michael Brohl  wrote:
> Maybe I was not clear enough... I am suggesting some kind of style guide.
>
> I think if we provide it in the early stage, people might get inspired from
> it and have examples in a very compressed form. I find the several examples
> that I've studied very helpful but they are cluttered all over the internet
> so it could be a shortcut for others.
>
> I will provide an example to make it clearer. Will take some days as I am
> off until coming Wednesday.
>
> Thanks,
>
> Michael Brohl
> ecomify GmbH
> www.ecomify.de
>
>
> Am 18.03.18 um 17:46 schrieb Taher Alkhateeb:
>
>> Hmmm, Sounds like a good idea, but perhaps maybe a bit early? We might
>> be still evolving and learning how to structure our documents.
>>
>> Also, maybe if we keep our documents clean and consistent, then they
>> themselves offer an example for how to write stuff? Examples usually
>> run out of date quickly unless we have some kind of mechanism in place
>> for always keeping them up to date. Anyway, if we decide to go that
>> route, [1] serves as a nice sample for us to imitate but with
>> instructions specific to OFBiz
>>
>> [1] https://asciidoctor.org/docs/asciidoc-recommended-practices/
>>
>> On Sun, Mar 18, 2018 at 7:35 PM, Michael Brohl 
>> wrote:
>>>
>>> Heyho,
>>>
>>> I played around with asciidoc a bit and did some minor changes to display
>>> a
>>> nice title page and did some configurations for the user/developer
>>> manuals.
>>>
>>> I studied a few example .adoc files and wonder if we should provide a
>>> best
>>> practice example .adoc file. This could contain all formatting,
>>> guidelines
>>> to mark special contents (info, attention, citations etc.) or how to
>>> format
>>> code examples.
>>>
>>> It would be a guideline as well as an example to learn from. I am hoping
>>> that it is easier for people to get started and it could also improve the
>>> quality.
>>>
>>> This document itself could be in the codebase and evolve over time.
>>>
>>> What do you think?
>>>
>>> Regards,
>>>
>>> Michael Brohl
>>> ecomify GmbH
>>> www.ecomify.de
>>>
>>>
>>>
>
>

Re: [DOC] Example asciidoc file as guideline

[Michael Brohl]

Maybe I was not clear enough... I am suggesting some kind of style guide.

I think if we provide it in the early stage, people might get inspired 
from it and have examples in a very compressed form. I find the several 
examples that I've studied very helpful but they are cluttered all over 
the internet so it could be a shortcut for others.


I will provide an example to make it clearer. Will take some days as I 
am off until coming Wednesday.


Thanks,

Michael Brohl
ecomify GmbH
www.ecomify.de


Am 18.03.18 um 17:46 schrieb Taher Alkhateeb:

Hmmm, Sounds like a good idea, but perhaps maybe a bit early? We might
be still evolving and learning how to structure our documents.

Also, maybe if we keep our documents clean and consistent, then they
themselves offer an example for how to write stuff? Examples usually
run out of date quickly unless we have some kind of mechanism in place
for always keeping them up to date. Anyway, if we decide to go that
route, [1] serves as a nice sample for us to imitate but with
instructions specific to OFBiz

[1] https://asciidoctor.org/docs/asciidoc-recommended-practices/

On Sun, Mar 18, 2018 at 7:35 PM, Michael Brohl  wrote:

Heyho,

I played around with asciidoc a bit and did some minor changes to display a
nice title page and did some configurations for the user/developer manuals.

I studied a few example .adoc files and wonder if we should provide a best
practice example .adoc file. This could contain all formatting, guidelines
to mark special contents (info, attention, citations etc.) or how to format
code examples.

It would be a guideline as well as an example to learn from. I am hoping
that it is easier for people to get started and it could also improve the
quality.

This document itself could be in the codebase and evolve over time.

What do you think?

Regards,

Michael Brohl
ecomify GmbH
www.ecomify.de








smime.p7s
Description: S/MIME Cryptographic Signature

Re: [DOC] Example asciidoc file as guideline

[Taher Alkhateeb]

Hmmm, Sounds like a good idea, but perhaps maybe a bit early? We might
be still evolving and learning how to structure our documents.

Also, maybe if we keep our documents clean and consistent, then they
themselves offer an example for how to write stuff? Examples usually
run out of date quickly unless we have some kind of mechanism in place
for always keeping them up to date. Anyway, if we decide to go that
route, [1] serves as a nice sample for us to imitate but with
instructions specific to OFBiz

[1] https://asciidoctor.org/docs/asciidoc-recommended-practices/

On Sun, Mar 18, 2018 at 7:35 PM, Michael Brohl  wrote:
> Heyho,
>
> I played around with asciidoc a bit and did some minor changes to display a
> nice title page and did some configurations for the user/developer manuals.
>
> I studied a few example .adoc files and wonder if we should provide a best
> practice example .adoc file. This could contain all formatting, guidelines
> to mark special contents (info, attention, citations etc.) or how to format
> code examples.
>
> It would be a guideline as well as an example to learn from. I am hoping
> that it is easier for people to get started and it could also improve the
> quality.
>
> This document itself could be in the codebase and evolve over time.
>
> What do you think?
>
> Regards,
>
> Michael Brohl
> ecomify GmbH
> www.ecomify.de
>
>
>

[DOC] Example asciidoc file as guideline

[Michael Brohl]

Heyho,

I played around with asciidoc a bit and did some minor changes to 
display a nice title page and did some configurations for the 
user/developer manuals.


I studied a few example .adoc files and wonder if we should provide a 
best practice example .adoc file. This could contain all formatting, 
guidelines to mark special contents (info, attention, citations etc.) or 
how to format code examples.


It would be a guideline as well as an example to learn from. I am hoping 
that it is easier for people to get started and it could also improve 
the quality.


This document itself could be in the codebase and evolve over time.

What do you think?

Regards,

Michael Brohl
ecomify GmbH
www.ecomify.de





smime.p7s
Description: S/MIME Cryptographic Signature