You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Lukasz Lenart <lu...@apache.org> on 2017/01/28 08:33:16 UTC
Documentation
Hi,
I would like to move our docs (or some part of it) to Markdown and put
them next to our website's source. Existing mechanism of exporting
docs is rather not the best approach, also it isn't possible to engage
community to improve it (as with the core and PRs via GitHub).
My first idea was to export everything from Confluence and convert to
MD but this not the best approach after all - we still need a place to
restrict access for some pages, i.e. security bulletins and so on,
also some pages are to detailed to be part of so common user guides.
So instead of migrating things I think it would be better to start
writing/copy/pasting some parts from wiki directly to website and
create a new/based on old guides. Confluence will be still used for
more detailed explanations of core elements and to manage releases and
so on.
I want to start with
https://cwiki.apache.org/confluence/display/WW/Getting+Started
or more generally with
https://cwiki.apache.org/confluence/display/WW/Tutorials
wdyt?
Regards
--
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation
Posted by Lukasz Lenart <lu...@apache.org>.
2017-01-31 18:29 GMT+01:00 Ken McWilliams <ke...@gmail.com>:
> Anything that makes document contribution easier is good!
>
> A traditional wiki in my opinion would be most ideal. Just as it works for
> Wikipedia (backed by mediawiki) you'll find that very few people will cause
> an issue with documentation. It is also very beneficial if people can
> create new pages/links too. All wikis have security to restrict certain
> pages to certain users, so security bulletins etc. can be trusted. It is
> really nice when you find a spelling error to just fix it then and there. A
> wiki I like is Xwiki it's Java based and it happily cooperates with most
> any DB. Both these wiki's are _very_ easy to set up. I think Xwiki uses
> Struts... I think v2...It is a pretty nice and useful product (FLOSS).
>
> A plausible option would be to create a wiki and export it's pages into the
> main site. Not sure about that sort of flow but for the paranoid it would
> allow an official checked version to exist, as well as a faster evolving
> version. At the worst move the content with copy and paste.
ASF is using Confluence [1] or MoinMoin Wiki [2] - these are the only
options we have ;-) I would like to use git [3] for
version-controlling and for easy maintenance and contributions - you
don't have to clone a fork locally, you can edit markdown files
directly in a browser and create PRs. Also using git allow us to use
Jenkins to automatically deploy a new version of website & docs.
Right now I'm using this [4] to export all the pages from Confluence
and put them inside a website production repo [5] - it's a bit painful
and cumbersome process ;-)
[1] cwiki.apache.org/confluence/display/WW/
[2] https://wiki.apache.org/general/
[3] https://github.com/apache/struts-site
[4] https://github.com/apache/struts-site/blob/master/pom.xml#L27-L46
[5] https://svn.apache.org/repos/infra/websites/production/struts/content/
Regards
--
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation
Posted by Ken McWilliams <ke...@gmail.com>.
Anything that makes document contribution easier is good!
A traditional wiki in my opinion would be most ideal. Just as it works for
Wikipedia (backed by mediawiki) you'll find that very few people will cause
an issue with documentation. It is also very beneficial if people can
create new pages/links too. All wikis have security to restrict certain
pages to certain users, so security bulletins etc. can be trusted. It is
really nice when you find a spelling error to just fix it then and there. A
wiki I like is Xwiki it's Java based and it happily cooperates with most
any DB. Both these wiki's are _very_ easy to set up. I think Xwiki uses
Struts... I think v2...It is a pretty nice and useful product (FLOSS).
A plausible option would be to create a wiki and export it's pages into the
main site. Not sure about that sort of flow but for the paranoid it would
allow an official checked version to exist, as well as a faster evolving
version. At the worst move the content with copy and paste.
On Tue, Jan 31, 2017 at 5:04 AM, Stefaan Dutry <st...@gmail.com>
wrote:
> Hello,
>
> I like the idea.
> I wouldn't mind helping with migrating the documentation.
>
> I would need at least 1 page as an example, and to know the exact
> location where you want the documentation to be placed.
>
> Regards,
>
> Stefaan Dutry
> (sdutry)
>
> Op 31 jan. 2017 10:45 a.m. schreef "Lukasz Lenart" <
> lukaszlenart@apache.org>:
> >
> > 2017-01-31 10:43 GMT+01:00 Christoph Nenning <
> Christoph.Nenning@lex-com.net>:
> > > Hi,
> > >
> > > sounds like a good idea!
> > >
> > > But also sounds like a lot of work. It will take probably plenty of
> time
> > > until it is finished. Every journey starts with a first step :)
> >
> > Not really a plenty of work as I want to just copy paste existing
> > Getting Started ;-) And then improved it over the time :)
> >
> >
> > Regards
> > --
> > Łukasz
> > + 48 606 323 122 http://www.lenart.org.pl/
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> > For additional commands, e-mail: dev-help@struts.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
--
Sent from my C64 using a 300 baud modem
Re: Documentation
Posted by Lukasz Lenart <lu...@apache.org>.
2017-01-31 13:04 GMT+01:00 Stefaan Dutry <st...@gmail.com>:
> Hello,
>
> I like the idea.
> I wouldn't mind helping with migrating the documentation.
>
> I would need at least 1 page as an example, and to know the exact
> location where you want the documentation to be placed.
The website's source is here https://github.com/apache/struts-site and
I want to start adding pages to it, it can be in the root folder
Regards
--
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation
Posted by Stefaan Dutry <st...@gmail.com>.
Hello,
I like the idea.
I wouldn't mind helping with migrating the documentation.
I would need at least 1 page as an example, and to know the exact
location where you want the documentation to be placed.
Regards,
Stefaan Dutry
(sdutry)
Op 31 jan. 2017 10:45 a.m. schreef "Lukasz Lenart" <lu...@apache.org>:
>
> 2017-01-31 10:43 GMT+01:00 Christoph Nenning <Ch...@lex-com.net>:
> > Hi,
> >
> > sounds like a good idea!
> >
> > But also sounds like a lot of work. It will take probably plenty of time
> > until it is finished. Every journey starts with a first step :)
>
> Not really a plenty of work as I want to just copy paste existing
> Getting Started ;-) And then improved it over the time :)
>
>
> Regards
> --
> Łukasz
> + 48 606 323 122 http://www.lenart.org.pl/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation
Posted by Lukasz Lenart <lu...@apache.org>.
2017-01-31 10:43 GMT+01:00 Christoph Nenning <Ch...@lex-com.net>:
> Hi,
>
> sounds like a good idea!
>
> But also sounds like a lot of work. It will take probably plenty of time
> until it is finished. Every journey starts with a first step :)
Not really a plenty of work as I want to just copy paste existing
Getting Started ;-) And then improved it over the time :)
Regards
--
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation
Posted by Christoph Nenning <Ch...@lex-com.net>.
Hi,
sounds like a good idea!
But also sounds like a lot of work. It will take probably plenty of time
until it is finished. Every journey starts with a first step :)
Regards,
Christoph
>
> Hi,
>
> I would like to move our docs (or some part of it) to Markdown and put
> them next to our website's source. Existing mechanism of exporting
> docs is rather not the best approach, also it isn't possible to engage
> community to improve it (as with the core and PRs via GitHub).
>
> My first idea was to export everything from Confluence and convert to
> MD but this not the best approach after all - we still need a place to
> restrict access for some pages, i.e. security bulletins and so on,
> also some pages are to detailed to be part of so common user guides.
>
> So instead of migrating things I think it would be better to start
> writing/copy/pasting some parts from wiki directly to website and
> create a new/based on old guides. Confluence will be still used for
> more detailed explanations of core elements and to manage releases and
> so on.
>
> I want to start with
> https://cwiki.apache.org/confluence/display/WW/Getting+Started
>
> or more generally with
> https://cwiki.apache.org/confluence/display/WW/Tutorials
>
> wdyt?
>
>
> Regards
> --
> Łukasz
> + 48 606 323 122 http://www.lenart.org.pl/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
This Email was scanned by Sophos Anti Virus