Migration is done.
From now on, only use:
https://docs.jboss.org/author/display/GTNPORTAL35 to add documentation.
The docs on GitHub will be removed very soon:
https://github.com/gatein/gatein-portal/pull/180
To use confluence and use the right styles, please have a look at:
https://docs.jboss.org/author/display/AUTHGUIDE/Markup+Guide
I already added 2 metadata info:
{space-metadata-from:projectVersionNumber} -> 3.5
{space-metadata-from:projectName} -> GateIn Portal
Anyone can review the doc, make changes and/or add comments.
In the following weeks, we will be looking at consolidating some docs
coming from the Wiki and rearrange chapters.
User Guide: It's really the click-through document, doesn't have much value
Reference Guide: It's the place to find all the tiny details about
everything
Developer Guide: Should be the place to start for all developers,
explains how to take decision and how to achieve tasks. It refers to the
reference guide for more details. It should be straight to the point and
not give the gazillion options, just the one we advise and make it clear.
Administration Guide: This is targeted to administrators and should evolve.
We will probably put back an Installation Guide too.
Difference between Developer Guide and Reference Guide through one
example: JSF App with Portlet Bridge
In the developer guide we should explain that JSF can be used to write
applications, explain how to package the application... (Kind of what
https://docs.jboss.org/author/display/PBR/Getting+Started does)
In the reference guide we would explain all the config options of
PortletBridge. (Kind of what
https://docs.jboss.org/author/display/PBR/User+Guide does. I'm trying to
get it renamed to "Reference Guide" ;))
PS: PortletBridge docs remains separated, it was just to illustrate.
Thanks,
Thomas
On 09/28/2012 12:49 PM, Thomas Heute wrote:
There were 2 questions/comments:
- Can we keep semantic of docbook ?
Answer is no. The Wysiwyg and WIKI markup have smaller scope for
semantic (which isn't bad as we tend to use different semantic in
docbook for the samething such as programlisting vs code).
There is an authoring guide here that I would recommend to follow even
though, it's quite natural:
https://docs.jboss.org/author/display/AUTHGUIDE/Markup+Guide
- Cross-reference links (to sections) are broken.
Indeed there is an issue here, it works fine when it references a
chapter but not a section. I mentioned the issue but I prefer not to
wait on resolution. There are 52 links like that that are broken, I'm
still checking if I can fix them prior to the import, otherwise I will
fix some when reviewing the doc.
I won't migrate today because of the second issue, so for now, please
continue with docbook in GIT.
Thanks,
Thomas.
On 09/24/2012 04:55 PM, Thomas Heute wrote:
> We are moving docs from docbook in Git to Confluence on
jboss.org.
>
> Confluence has the option to use a WYSIWYG editor or a Wiki markup
> editor, it instantly gives you something easy to read.
>
> I migrated user guide and reference guide for check here, it seems that
> it worked pretty nicely:
>
https://docs.jboss.org/author/display/GTNPORTAL35
>
> I want to give a few days so that people can check that the migration
> process is ok.
>
> It there is no objection, on Friday I will take the latest from Git and
> regenerate those docs and send an email here. I will also delete the
> docs folder from our Git repository.
>
> From that moment, any doc change will have to be done through:
>
https://docs.jboss.org/author/display/GTNPORTAL35
>
> Thanks,
> Thomas.
>
>
>
> _______________________________________________
> gatein-dev mailing list
> gatein-dev(a)lists.jboss.org
>
https://lists.jboss.org/mailman/listinfo/gatein-dev
>
_______________________________________________
gatein-dev mailing list
gatein-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/gatein-dev