Hi all,

it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
To solve this situation I did some work in the past few days and want to propose following.
This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

1. Kill the Wiki

Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
Lets take following into consideration though:

- The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
- The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
- The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
- The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

2. Move everything to SVN (or whatever vcs you want)

- This way we will have one channel of communication (vs. >2 now)
- We can exactly track changes been made
- We can tag doc releases much easier than we do now because the process is too complicated
- We can revert doc changes
- We finally can offer offline or even PDF downloads on a regular base

Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
Possible enhancements are:

- Make it work/test on windows (only rewriting a shell script.
- svn integration
- git integration
- API docs integration?

I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
If you think this is a problem, let me know and we can see if we can find a solution.
You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

3. The final doc process

- Everything is done via svn, svn is the only channel
- People can use the docwriter tool to make life a lot easier
- We have (should) set up a doc access group so people don't have to be committer to write docs
- At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
- We build up a doc team which is responsible of the quality

This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

4. Other issues/benefits

- We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
- No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
- People can add custom data/image/whatever files to the documentation

I would like to move further on this and this is the only solution I see which will be crystal clear.
I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

What do you think?

Nikolai

Search Discussions

  • Bill Keese at May 13, 2010 at 11:03 pm
    It's interesting. I guess it's a good idea. The downside is that it
    discourages casual contributors to the doc. One upside, besides
    avoiding issue w/what version of dojo is running on dojocampus.org, is
    that it's easier to make global doc changes, like replacing attr() with
    set() and get().

    To confirm, you are talking about keeping the same REST format (with out
    customizations for adding example code), but storing those REST format
    files into a separate SVN?
    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    What kind of conversion are you talking about? From REST format into
    HTML? Also, how is dojotoolkit.org stored? Is dojotoolkit.org in SVN
    too, and if so, what format (HTML/PHP/django/etc.)?

    Finally, how do you propose that changes in the doc SVN get pushed to
    http://dojotoolkit.org/documentation/?

    On 5/14/10 2:02 AM, Nikolai Onken wrote:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs.>2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Nikolai Onken at May 14, 2010 at 4:17 am

    To confirm, you are talking about keeping the same REST format (with out
    customizations for adding example code), but storing those REST format
    files into a separate SVN?
    Yes, the format stays. Right now we have to export all files from the Wiki so we can convert them into html.
    Exporting in this case means getting rid of Wiki specific things, normalizing paths, coping uploads, etc. which is cumbersome and prone to errors.
    This whole process is done manually right now (because of the risk of errors) using a couple of shell scripts.
    We then push the exported clean rest structure into svn losing the entire revision history.
    What kind of conversion are you talking about? From REST format into
    HTML? Also, how is dojotoolkit.org stored? Is dojotoolkit.org in SVN
    too, and if so, what format (HTML/PHP/django/etc.)? ...
    Finally, how do you propose that changes in the doc SVN get pushed to
    http://dojotoolkit.org/documentation/?
    To get the docs on dtk.org we then simply check out the latest release and run "make html" - from the clean rest structure, not from the Wiki structure.
    We do this already now, only do we have to prepare all this by cleaning up the messy Wiki rest structure first.

    So right now we have following process

    Wiki => export to convertable format (clean REST) => convert to html

    What I propose is

    REST => convert to html

    There are other reasons why the wiki makes things complicated such as the fact that we can't store custom files and link to them but this is the gist of it.

    Nikolai
    On 5/14/10 2:02 AM, Nikolai Onken wrote:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs.>2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Dustin Machi at May 13, 2010 at 11:12 pm
    I only have a couple of comments on this...

    - Keep in mind not all people have access to the svn repo for commit purposes. We should either a) keep this documentation in a separate svn repo if we need to be able to grant non-committers privileges to write to these docs or b) allow the documentation tool to push an svn patch to the bug system for someone else to commit.

    - I really dislike the url path for the docs. It is too long and more difficult to type than on docs.dojocampus.org. Because of this, I almost exclusively use the dojocampus doc wiki as is the case with many people on #dojo for this same reason. I would like to see an alias or something setup so we can use something like /ref/dijit/form/TextBox instead of /reference-guide/dijit/form/TextBox.html .

    Dustin
    On May 13, 2010, at 1:02 PM, Nikolai Onken wrote:

    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs. >2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Tom Elliott at May 14, 2010 at 3:19 am
    I agree with both those points...
    On 14 May 2010 04:12, Dustin Machi wrote:
    I only have a couple of comments on this...

    ? ? ? ?- ?Keep in mind not all people have access to the svn repo for commit purposes. ?We should either a) keep this documentation in a separate svn repo if we need to be able to grant non-committers privileges to write to these docs or b) allow the documentation tool to push an svn patch to the bug system for someone else to commit.

    ? ? ? ?- ?I really dislike the url path for the docs. ?It is too long and more difficult to type than on docs.dojocampus.org. ?Because of this, I almost exclusively use the dojocampus doc wiki as is the case with many people on #dojo for this same reason. ?I would like to see an alias or something setup so we can use something like /ref/dijit/form/TextBox instead of /reference-guide/dijit/form/TextBox.html .

    ?Dustin
    On May 13, 2010, at 1:02 PM, Nikolai Onken wrote:

    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs. >2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors


    --
    www.twistyfish.co.uk
  • Nikolai Onken at May 14, 2010 at 4:21 am
    - Keep in mind not all people have access to the svn repo for commit purposes. We should either a) keep this documentation in a separate svn repo if we need to be able to grant non-committers privileges to write to these docs or b) allow the documentation tool to push an svn patch to the bug system for someone else to commit.
    Right now the cleaned REST files are stored here: https://svn.dojotoolkit.org/dojo_doc_wiki

    I'd personally prefer something shorter :) like https://svn.dojotoolkit.org/docs but thats a detail...
    And yes it would be good if we easily can grant non-committers access to the doc wiki. b) is a good suggestion as well.
    - I really dislike the url path for the docs. It is too long and more difficult to type than on docs.dojocampus.org. Because of this, I almost exclusively use the dojocampus doc wiki as is the case with many people on #dojo for this same reason. I would like to see an alias or something setup so we can use something like /ref/dijit/form/TextBox instead of /reference-guide/dijit/form/TextBox.html .
    Agrees, same here, I prefer docs.dojocampus.org because I know exactly how things map. On dtk.org I never remember the reference-guide thing.
    URL mapping should solve this.

    Nikolai
    Dustin
    On May 13, 2010, at 1:02 PM, Nikolai Onken wrote:

    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs. >2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Brett Zamir at May 14, 2010 at 3:33 am

    On 5/14/2010 1:02 AM, Nikolai Onken wrote:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki
    <snip>
    2. Move everything to SVN (or whatever vcs you want)
    How about both--a system where the wiki can work off the VCS? (And get
    the benefits of Git too)

    Looking at some of the choices:

    https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools#Wikis.2C_blogs.2C_etc.
    http://www.wikimatrix.org/compare/Git-Wiki+gitit+WiGit

    ...the coolest looking one in my opinion is:
    http://git.awiki.org/Home
    http://git.awiki.org/Features
    http://git.awiki.org/Sandbox

    This one also looks like it may be all right:
    http://gitit.net/

    Brett
  • Nikolai Onken at May 14, 2010 at 5:13 am
    How about both--a system where the wiki can work off the VCS? (And get the benefits of Git too)
    We were hoping that the wiki we are using right now would allow this at some point - they have it on their roadmap.
    Right now my main insentive is to get rid of all tools in the chain which make streamlining and documenting the process easier.
    At this point if I want to explain to someone how the doc system works I have to write a whole manual.
    What I would like is:

    1. SVN repo is here...
    2. Docs use a tool called sphinx to convert REST to HTML
    3. If you don't like to edit plain text we have a tool here... If you think features are missing, add them to the tool.. its JavaScript and opensource
    4. To push docs live do following
    1. svn co
    2. make html

    Instead we have something like:

    1. We have a Wiki for editing the REST files
    2. The wiki uses a slight different syntax because its a Wiki, so we have a export process
    3. To push the Wiki contents live on dtk.org you have to do following
    1.
    2.
    3.
    4.
    5.
    6.
    7.
    4. The SVN repo is not really useful right now because you have to push changes from Wiki in one go, losing all history
    5. You can't work with the SVN repo directly because someone else might have edited the same page in the wiki...
    This looks good, though right now I wouldn't want to introduce a new tool in the chain. I really want to have less :)
    What do you think?

    Nikolai
    Brett
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: http://mail.dojotoolkit.org/pipermail/dojo-contributors/attachments/20100514/b96c1e38/attachment.htm
  • Tom Trenka at May 14, 2010 at 11:15 am

    Only a couple of comments from me as well:

    Right now my main insentive is to get rid of all tools in the chain which
    make streamlining and documenting the process easier.
    I'm all for streamlining the process, and I would also agree with
    Dustin's points (re: separate permissions, etc.). But I think there
    is a need for at least the following:

    1. Preview the ReST document in HTML.
    I don't think there's any way this will fly without (at least) having
    a tool where you can check the document you're working on, and make
    sure it actually works (including the Code Glass customizations) --
    WITHOUT having to build/convert the entire repo. I think this is the
    main reason why there is such resistance to moving away from the wiki;
    the wiki makes it very easy to check/preview your work.

    If there is a quick way of doing this, then I'm all for it.

    2. Organization
    The other thing about the wiki is that it creates the organization of
    the documentation. Now, I've never been a big fan of wikis (to me,
    navigation is the most important part of anything, and the
    haphazardness that wikis allow for can make it very difficult to find
    pertinent information), but at the same time there definitely needs to
    be a method of organization that can be/should be used to create
    navigation, at least when converting to HTML.

    -----

    I have a feeling that there is going to need to be a preview tool,
    along the lines of the quick-and-dirty browse2.php in
    util/docscripts...and I guess if someone wanted to get *real*
    creative, they could set up the dijit or dojox Editor as a way of
    editing documents. Either that, or there needs to be at least one
    editor out there that people can use to preview their docs (I only use
    VIM, obviously that's not going to convert a ReST doc for me ;) )
    Without that, I don't see how moving to pure ReST in SVN is going to
    help the documentation system at all (we actually started the original
    docs back in the 0.1 days that way, interesting to see it coming full
    circle).

    -- Tom
  • Nikolai Onken at May 14, 2010 at 12:29 pm
    Hi Tom,

    did you see http://static.uxebu.com/~nonken/dojo/DojoDocs.mov ?
    This would give you pretty much instant feedback of what you did - and is only a start.
    You have to press the build button (we can also automatically build when clicking preview) but the build only always rebuilds the modified files, therefore is fast.
    There is a whole lot more we could do with such a tool (example wizard, doc help, etc.)
    I have been writing documentation for one of our projects at uxebu using this tool now and find working with it much faster than using a wiki.
    You don't have to wait for page reloads and the whole latency the wiki/web creates.
    I kind of want to keep the tool separate from the process though, so we are not dependent on it and won't run into "no doc updates" anymore.

    Nikolai
    On May 14, 2010, at 5:15 PM, Tom Trenka wrote:

    Only a couple of comments from me as well:
    Right now my main insentive is to get rid of all tools in the chain which
    make streamlining and documenting the process easier.
    I'm all for streamlining the process, and I would also agree with
    Dustin's points (re: separate permissions, etc.). But I think there
    is a need for at least the following:

    1. Preview the ReST document in HTML.
    I don't think there's any way this will fly without (at least) having
    a tool where you can check the document you're working on, and make
    sure it actually works (including the Code Glass customizations) --
    WITHOUT having to build/convert the entire repo. I think this is the
    main reason why there is such resistance to moving away from the wiki;
    the wiki makes it very easy to check/preview your work.

    If there is a quick way of doing this, then I'm all for it.

    2. Organization
    The other thing about the wiki is that it creates the organization of
    the documentation. Now, I've never been a big fan of wikis (to me,
    navigation is the most important part of anything, and the
    haphazardness that wikis allow for can make it very difficult to find
    pertinent information), but at the same time there definitely needs to
    be a method of organization that can be/should be used to create
    navigation, at least when converting to HTML.

    -----

    I have a feeling that there is going to need to be a preview tool,
    along the lines of the quick-and-dirty browse2.php in
    util/docscripts...and I guess if someone wanted to get *real*
    creative, they could set up the dijit or dojox Editor as a way of
    editing documents. Either that, or there needs to be at least one
    editor out there that people can use to preview their docs (I only use
    VIM, obviously that's not going to convert a ReST doc for me ;) )
    Without that, I don't see how moving to pure ReST in SVN is going to
    help the documentation system at all (we actually started the original
    docs back in the 0.1 days that way, interesting to see it coming full
    circle).

    -- Tom
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: http://mail.dojotoolkit.org/pipermail/dojo-contributors/attachments/20100514/9eb69ede/attachment.htm
  • James Burke at May 14, 2010 at 2:20 pm

    On Thu, May 13, 2010 at 10:02 AM, Nikolai Onken wrote:
    What do you think?
    Sounds fine to me, as long as permissions work out, as Dustin
    mentioned, and the preview tool works well. Seems like your AIR tool
    will work out, although I would not mind instructions on how to
    manually build it via command line and just load with local
    browser/local web server.

    In general, I like the idea of docs we can edit via source control and
    commit. I really enjoy the github model now where it understands
    markdown, so after pushing to github you can see a first-pass
    text-to-HTML transform on the docs. Using github for the docs also
    might make it easier for others to contribute via forks, so I am fine
    if github is used to host the docs. Extra points for using markdown to
    mark up the docs, but I appreciate that might not be feasible with the
    "plugins" we use for codeglass and such. So just using a dvcs might be
    useful, and using github in particular might be useful from a hosting
    maintenance perspective.

    I write a very small amount of docs, so my comments above should be
    weighted accordingly.

    James
  • Tom Trenka at May 14, 2010 at 3:19 pm
    Markdown would be pretty nice/convenient, since the API docs also use
    it. Be nice to have a single format in that regard, though it would
    mean a major effort in terms of the current docs.

    -- Tom
    On Fri, May 14, 2010 at 1:20 PM, James Burke wrote:
    On Thu, May 13, 2010 at 10:02 AM, Nikolai Onken
    wrote:
    What do you think?
    Sounds fine to me, as long as permissions work out, as Dustin
    mentioned, and the preview tool works well. Seems like your AIR tool
    will work out, although I would not mind instructions on how to
    manually build it via command line and just load with local
    browser/local web server.

    In general, I like the idea of docs we can edit via source control and
    commit. I really enjoy the github model now where it understands
    markdown, so after pushing to github you can see a first-pass
    text-to-HTML transform on the docs. Using github for the docs also
    might make it easier for others to contribute via forks, so I am fine
    if github is used to host the docs. Extra points for using markdown to
    mark up the docs, but I appreciate that might not be feasible with the
    "plugins" we use for codeglass and such. So just using a dvcs might be
    useful, and using github in particular might be useful from a hosting
    maintenance perspective.

    I write a very small amount of docs, so my comments above should be
    weighted accordingly.

    James
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Nikolai Onken at May 14, 2010 at 4:01 pm

    Markdown would be pretty nice/convenient, since the API docs also use
    it. Be nice to have a single format in that regard, though it would
    mean a major effort in terms of the current docs.
    Github supports REST as well http://github.com/guides/readme-formatting if we would ever want to push docs to gihub.
    My main concern right now is that we should simplify the tool-chain. Everything else is working fine and should not be changed imo.

    Nikolai
    -- Tom
    On Fri, May 14, 2010 at 1:20 PM, James Burke wrote:
    On Thu, May 13, 2010 at 10:02 AM, Nikolai Onken
    wrote:
    What do you think?
    Sounds fine to me, as long as permissions work out, as Dustin
    mentioned, and the preview tool works well. Seems like your AIR tool
    will work out, although I would not mind instructions on how to
    manually build it via command line and just load with local
    browser/local web server.

    In general, I like the idea of docs we can edit via source control and
    commit. I really enjoy the github model now where it understands
    markdown, so after pushing to github you can see a first-pass
    text-to-HTML transform on the docs. Using github for the docs also
    might make it easier for others to contribute via forks, so I am fine
    if github is used to host the docs. Extra points for using markdown to
    mark up the docs, but I appreciate that might not be feasible with the
    "plugins" we use for codeglass and such. So just using a dvcs might be
    useful, and using github in particular might be useful from a hosting
    maintenance perspective.

    I write a very small amount of docs, so my comments above should be
    weighted accordingly.

    James
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Marcus Reimann at May 15, 2010 at 6:06 am
    It's more a question to choose the right tool for the job.

    Whether SVN nor Github is the right platform for documentation. We all
    know, how much time a checkin within a SVN costs, instead of a simple
    preview or save within a WIKI. Also getting updates is very slow with
    SVN. I don't think I will be happy to wait for a SVN checkout, in order
    to start editing, just for the sake of using SVN instead of a WIKI.

    Furthermore, I question at which point, to which time we really need the
    files in SVN or not. The only reason for this, could be to handle the
    exported HTML pages for different Dojo versions. But this is a task at
    the end of the documentation process and would be a simple task for an
    Export Shell script. I will create this Shell script, which will do all
    the WIKI specific things, normalizing paths, copying the results to the
    right directory and/or remote servers, whenever you'll find the time to
    tell me some more details (I've already offered my support for something
    like this on several occasions to Dustin, Peter, Tobias and Nikolai).
    So, no more manually steps will be necessary and the Export Shell script
    will run every night.

    We have already seen what happens, when tools like a forum are closed. A
    lot of users are discussing about Dojo in other forums, but not in the
    original Dojo Toolkit forum or mailing list. We will see the same with
    documentation. Or could you explain me, why users should use a SVN tool
    for a short edit? If dojocampus.org/dojotoolkit.org offers no more tools
    like a WIKI, then it's only a question of time when we will see other
    WIKIs for offering this service instead.

    Regards,
    Marcus

    --
    http://www.dojotoolkit-forum.de



    Am 13.05.2010 19:02, schrieb Nikolai Onken:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs.>2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Marcus Reimann at May 15, 2010 at 1:04 pm
    Whether SVN nor Github is the right platform for documentation.
    Sorry, what I meant was not "Whether SVN or Github...".

    Instead I meant that "Neither SVN nor Github is the right platform for
    documentation."

    In my eyes, the current idea to use SVN (or Github) is not the best for
    docs.

    Marcus
  • Nikolai Onken at May 16, 2010 at 3:22 pm
    It's more a question to choose the right tool for the job.
    To me right now it is most important that we use a system which does not depend on a person knowing how it works.
    And this to me at least leads to some files using some data format (reST) and a storage system which everybody knows (svn, whatever).
    We see this happening right now - the people who know how it currently works (me included) are super busy and having a hard time freeing up time to do the work which needs to be done.
    Whether SVN nor Github is the right platform for documentation. We all
    know, how much time a checkin within a SVN costs, instead of a simple
    preview or save within a WIKI. Also getting updates is very slow with
    SVN. I don't think I will be happy to wait for a SVN checkout, in order
    to start editing, just for the sake of using SVN instead of a WIKI.
    I don't have the issues you have. Working with SVN or GIT is something I do every day and it does not slow down my work.
    Yes getting the initial checkout may take some time but the benefits of a vcs still weigh out the disadvantages.
    Furthermore, I question at which point, to which time we really need the
    files in SVN or not. The only reason for this, could be to handle the
    exported HTML pages for different Dojo versions. But this is a task at
    This is super essential. We want to be able to deliver the 1.3 docs, or 1.4 docs (at least in my opinion) as much as we want to have all the benefits of version control in general.
    Especially when having real code examples. If we can't tag doc releases how will we keep old versions?
    the end of the documentation process and would be a simple task for an
    Export Shell script. I will create this Shell script, which will do all
    the WIKI specific things, normalizing paths, copying the results to the
    right directory and/or remote servers, whenever you'll find the time to
    tell me some more details (I've already offered my support for something
    like this on several occasions to Dustin, Peter, Tobias and Nikolai).
    This is great but again does not address the issue of keeping the setup simple.
    What will happen if you will be too busy and don't have time anymore to maintain the work?
    So, no more manually steps will be necessary and the Export Shell script
    will run every night.
    To me such a process will be (as it already is) too prone to errors.
    We have already seen what happens, when tools like a forum are closed. A
    lot of users are discussing about Dojo in other forums, but not in the
    original Dojo Toolkit forum or mailing list. We will see the same with
    documentation. Or could you explain me, why users should use a SVN tool
    I think it is important to distinguish here between who we are talking to.
    With the mailing list we were changing the works of a direct interface to every dojo user and that had negative impact
    With the doc editing interface we don't (at least in my opinion). There should be one place and one place only for people wanting to check out the docs and that place is dojotoolkit.org.
    Dojocampus was always a temporary solution until the new website was done, now it is, and now we should create that clarity.
    for a short edit? If dojocampus.org/dojotoolkit.org offers no more tools
    like a WIKI, then it's only a question of time when we will see other
    WIKIs for offering this service instead.
    If we had everything based on SVN only we could open up to other editing interfaces.
    Right now we can't because the WIKI determines how everything works. If you change a file via svn and then run the wiki export it will overwrite that.
    So, in that regards moving to SVN only could be the start for such tools (as the AIR tool is) - the advantage would be that these tools will be maintained by people.
    If those people stop working on the tools the docs will still work as always. Right now as we see happening, as soon as people are getting busy the process is borken and thats bad.

    Nikolai
    Regards,
    Marcus

    --
    http://www.dojotoolkit-forum.de



    Am 13.05.2010 19:02, schrieb Nikolai Onken:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs.>2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Dylan Schiemann at May 17, 2010 at 4:07 am
    Ok, I'm trying to understand what we're doing now, so I had a look at
    dojox.av.FLAudio as an instructive example. I chose this one because
    according to the todo list, http://docs.dojocampus.org/todo :

    needed: errors in the example, no audio directory within tests available
    on the server

    I went to http://docs.dojocampus.org/dojox/av/FLAudio , logged in, and
    fixed the error within the example (missing the object name on one of
    the method calls). This successfully fixes the example at
    http://docs.dojocampus.org/dojox/av/FLAudio , but only when played
    against trunk. The campus site only lets you choose trunk, 1.3. or 1.2.
    If we say it is only available with 1.3 or later, why are we allowing
    the user to choose 1.2?

    So, how does someone choose the version of docs and version of Dojo?

    Nest, looking at
    http://dojotoolkit.org/reference-guide/dojox/av/FLAudio.html , when does
    this get updated? With each major release? None of the examples work
    here, because you can only choose against 1.4, 1.3, or 1.2, none of
    which work with the example.

    Where's the 1.5 beta love? If people are trying out 1.5, there's
    nothing for them to work against at the moment.

    Also, we have this heading for each doc:

    Status: Draft
    Version: 1.0
    Project owner: Mike Wilcox, Tom Trenka
    Author: Mike Wilcox
    Available: since 1.3

    Does status correspond to the documentation or the module?

    What does the version number represent? It's likely confusing when
    comparing it to the explanation of Available.

    Project Owner and Author... is Author the author of the docs, or of the
    source code? How do I get in touch with them if there's a problem? How
    do I file a bug against the docs or the source code? (I know how, but
    why aren't we providing useful links, such as a link to known issues, a
    place to add links to known demos/tutorials, use cases, etc.? Instead,
    we're taking up a lot of screen real estate with the Documentation and
    Table of Contents navigation without offering a lot of real value there)

    Finally, there's a lot of documentation in the source code itself at
    http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/av/FLAudio.js .
    None of this appears on the documentation page. Nor does a mechanism
    exist for the visitor to the page to view the source code of the module
    itself.


    So, all of that said, I think it's pretty clear we need some changes. I
    watched Nikolai's screencast. I think it potentially looks like a nice
    solution, but it leaves me with a few questions.

    * Is there anything this fundamentally does that the wiki couldn't also
    be made to to? In other words, couldn't the wiki also be made to
    connect to svn/git, allow for file uploads, etc.? So far no one has
    solved these problems, I get that... but in essence the AIR app is the
    right approach for a committer, but not for a casual doc contributor (do
    we even have any casual doc contributors, or is it too much effort even
    now)?

    * What's the proposed save -> commit -> update the site process that's
    being proposed?

    * Other types of docs such as tutorials and demos, how does someone add
    those? Are they kept as content somewhere with the site or within this
    app? What happens to stuff like the key links (which really needs a
    rethink anyway).

    * How do we solve some of the other fundamental problems with the docs
    that have little to do with the actual tooling choices?

    Regards,
    - -Dylan

    on 5/16/10 12:22 PM (GMT-07:00) Nikolai Onken said the following:
    It's more a question to choose the right tool for the job.
    To me right now it is most important that we use a system which does not depend on a person knowing how it works.
    And this to me at least leads to some files using some data format (reST) and a storage system which everybody knows (svn, whatever).
    We see this happening right now - the people who know how it currently works (me included) are super busy and having a hard time freeing up time to do the work which needs to be done.
    Whether SVN nor Github is the right platform for documentation. We all
    know, how much time a checkin within a SVN costs, instead of a simple
    preview or save within a WIKI. Also getting updates is very slow with
    SVN. I don't think I will be happy to wait for a SVN checkout, in order
    to start editing, just for the sake of using SVN instead of a WIKI.
    I don't have the issues you have. Working with SVN or GIT is something I do every day and it does not slow down my work.
    Yes getting the initial checkout may take some time but the benefits of a vcs still weigh out the disadvantages.
    Furthermore, I question at which point, to which time we really need the
    files in SVN or not. The only reason for this, could be to handle the
    exported HTML pages for different Dojo versions. But this is a task at
    This is super essential. We want to be able to deliver the 1.3 docs, or 1.4 docs (at least in my opinion) as much as we want to have all the benefits of version control in general.
    Especially when having real code examples. If we can't tag doc releases how will we keep old versions?
    the end of the documentation process and would be a simple task for an
    Export Shell script. I will create this Shell script, which will do all
    the WIKI specific things, normalizing paths, copying the results to the
    right directory and/or remote servers, whenever you'll find the time to
    tell me some more details (I've already offered my support for something
    like this on several occasions to Dustin, Peter, Tobias and Nikolai).
    This is great but again does not address the issue of keeping the setup simple.
    What will happen if you will be too busy and don't have time anymore to maintain the work?
    So, no more manually steps will be necessary and the Export Shell script
    will run every night.
    To me such a process will be (as it already is) too prone to errors.
    We have already seen what happens, when tools like a forum are closed. A
    lot of users are discussing about Dojo in other forums, but not in the
    original Dojo Toolkit forum or mailing list. We will see the same with
    documentation. Or could you explain me, why users should use a SVN tool
    I think it is important to distinguish here between who we are talking to.
    With the mailing list we were changing the works of a direct interface to every dojo user and that had negative impact
    With the doc editing interface we don't (at least in my opinion). There should be one place and one place only for people wanting to check out the docs and that place is dojotoolkit.org.
    Dojocampus was always a temporary solution until the new website was done, now it is, and now we should create that clarity.
    for a short edit? If dojocampus.org/dojotoolkit.org offers no more tools
    like a WIKI, then it's only a question of time when we will see other
    WIKIs for offering this service instead.
    If we had everything based on SVN only we could open up to other editing interfaces.
    Right now we can't because the WIKI determines how everything works. If you change a file via svn and then run the wiki export it will overwrite that.
    So, in that regards moving to SVN only could be the start for such tools (as the AIR tool is) - the advantage would be that these tools will be maintained by people.
    If those people stop working on the tools the docs will still work as always. Right now as we see happening, as soon as people are getting busy the process is borken and thats bad.

    Nikolai
    Regards,
    Marcus

    --
    http://www.dojotoolkit-forum.de



    Am 13.05.2010 19:02, schrieb Nikolai Onken:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs.>2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Nikolai Onken at May 17, 2010 at 9:25 am

    Where's the 1.5 beta love? If people are trying out 1.5, there's
    nothing for them to work against at the moment.
    Yes, we don't have that right now because the process of updating each instance of available docs (wiki, dtk.org/docs) is more involved than it should be.
    In my opinion this should be something equivalent to a svn up but right now it isn't.
    Also, we have this heading for each doc:

    Status: Draft
    Version: 1.0
    Project owner: Mike Wilcox, Tom Trenka
    Author: Mike Wilcox
    Available: since 1.3

    Does status correspond to the documentation or the module?
    This needs clarification, agreed.
    What does the version number represent? It's likely confusing when
    comparing it to the explanation of Available.
    Not clear either. We could change it to "Available since"
    Project Owner and Author... is Author the author of the docs, or of the
    source code? How do I get in touch with them if there's a problem? How
    do I file a bug against the docs or the source code? (I know how, but
    why aren't we providing useful links, such as a link to known issues, a
    place to add links to known demos/tutorials, use cases, etc.? Instead,
    we're taking up a lot of screen real estate with the Documentation and
    Table of Contents navigation without offering a lot of real value there) Agreed.
    Finally, there's a lot of documentation in the source code itself at
    http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/av/FLAudio.js .
    None of this appears on the documentation page. Nor does a mechanism
    exist for the visitor to the page to view the source code of the module
    itself.
    Would be a nice feature to add to the docs.
    So, all of that said, I think it's pretty clear we need some changes. I
    watched Nikolai's screencast. I think it potentially looks like a nice
    solution, but it leaves me with a few questions.

    * Is there anything this fundamentally does that the wiki couldn't also
    be made to to? In other words, couldn't the wiki also be made to
    connect to svn/git, allow for file uploads, etc.? So far no one has
    solved these problems, I get that... but in essence the AIR app is the
    right approach for a committer, but not for a casual doc contributor (do
    we even have any casual doc contributors, or is it too much effort even
    now)?
    Right now the wiki blocks any other potential solution.
    Because the wiki does not integrate with svn we have to manually export and that is very prone to errors as I wrote.
    My AIR app is an example of one possible tool which can make life easier for certain people while it doesn't block the progression of the documentation itself.
    If at some point I decide not to maintain the AIR tool anymore, so be it, it won't break the documentation though and that is important.
    So, yes we could check if there is a wiki which would allow us to edit the rest files. We also could port the AIR tool to work online (not too difficult even).
    Right now though we don't have a process which is not dependent on a tool and thats bad. If someone then wants to put up resources to get a wiki running, awesome, that would be great!
    Regarding the casual doc writer - we don't really have those (http://docs.dojocampus.org/RecentChanges) - which should not mean that we shouldn't target them as well.
    * What's the proposed save -> commit -> update the site process that's
    being proposed?
    - Docs are hosted in a vcs (I suggest svn at this point because that is what Dojo uses and that is where the docs are currently stored in)
    - People can use their own tools to make the doc editing + svn commit process easy. One already existing helper tool could be the AIR app.

    Website update

    - Each dojo doc version gets tagged.
    - Once a release is tagged we convert it to HTML (make html)
    - We can host trunk docs under a dedicated url/folder to allow people to play around with nightly builds (cron)

    Essentially everything is already in place (svn, make html) - what blocks movement right now is the fact that we need to keep several instances of the docs up to date.
    * Other types of docs such as tutorials and demos, how does someone add
    those? Are they kept as content somewhere with the site or within this
    app? What happens to stuff like the key links (which really needs a
    rethink anyway).
    We can have tutorials in the docs, though I am sure that should not be the sole place for them to reside.. needs thinking.
    * How do we solve some of the other fundamental problems with the docs
    that have little to do with the actual tooling choices?
    Concretely I have to think about comments - jquery uses http://disqus.com/comments/ would be curious to hear what experience they have made.

    Nikolai

    Regards,
    - -Dylan

    on 5/16/10 12:22 PM (GMT-07:00) Nikolai Onken said the following:
    It's more a question to choose the right tool for the job.
    To me right now it is most important that we use a system which does not depend on a person knowing how it works.
    And this to me at least leads to some files using some data format (reST) and a storage system which everybody knows (svn, whatever).
    We see this happening right now - the people who know how it currently works (me included) are super busy and having a hard time freeing up time to do the work which needs to be done.
    Whether SVN nor Github is the right platform for documentation. We all
    know, how much time a checkin within a SVN costs, instead of a simple
    preview or save within a WIKI. Also getting updates is very slow with
    SVN. I don't think I will be happy to wait for a SVN checkout, in order
    to start editing, just for the sake of using SVN instead of a WIKI.
    I don't have the issues you have. Working with SVN or GIT is something I do every day and it does not slow down my work.
    Yes getting the initial checkout may take some time but the benefits of a vcs still weigh out the disadvantages.
    Furthermore, I question at which point, to which time we really need the
    files in SVN or not. The only reason for this, could be to handle the
    exported HTML pages for different Dojo versions. But this is a task at
    This is super essential. We want to be able to deliver the 1.3 docs, or 1.4 docs (at least in my opinion) as much as we want to have all the benefits of version control in general.
    Especially when having real code examples. If we can't tag doc releases how will we keep old versions?
    the end of the documentation process and would be a simple task for an
    Export Shell script. I will create this Shell script, which will do all
    the WIKI specific things, normalizing paths, copying the results to the
    right directory and/or remote servers, whenever you'll find the time to
    tell me some more details (I've already offered my support for something
    like this on several occasions to Dustin, Peter, Tobias and Nikolai).
    This is great but again does not address the issue of keeping the setup simple.
    What will happen if you will be too busy and don't have time anymore to maintain the work?
    So, no more manually steps will be necessary and the Export Shell script
    will run every night.
    To me such a process will be (as it already is) too prone to errors.
    We have already seen what happens, when tools like a forum are closed. A
    lot of users are discussing about Dojo in other forums, but not in the
    original Dojo Toolkit forum or mailing list. We will see the same with
    documentation. Or could you explain me, why users should use a SVN tool
    I think it is important to distinguish here between who we are talking to.
    With the mailing list we were changing the works of a direct interface to every dojo user and that had negative impact
    With the doc editing interface we don't (at least in my opinion). There should be one place and one place only for people wanting to check out the docs and that place is dojotoolkit.org.
    Dojocampus was always a temporary solution until the new website was done, now it is, and now we should create that clarity.
    for a short edit? If dojocampus.org/dojotoolkit.org offers no more tools
    like a WIKI, then it's only a question of time when we will see other
    WIKIs for offering this service instead.
    If we had everything based on SVN only we could open up to other editing interfaces.
    Right now we can't because the WIKI determines how everything works. If you change a file via svn and then run the wiki export it will overwrite that.
    So, in that regards moving to SVN only could be the start for such tools (as the AIR tool is) - the advantage would be that these tools will be maintained by people.
    If those people stop working on the tools the docs will still work as always. Right now as we see happening, as soon as people are getting busy the process is borken and thats bad.

    Nikolai
    Regards,
    Marcus

    --
    http://www.dojotoolkit-forum.de



    Am 13.05.2010 19:02, schrieb Nikolai Onken:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs.>2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    -----BEGIN PGP SIGNATURE-----
    Version: GnuPG v1.4.9 (Darwin)
    Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

    iEYEARECAAYFAkvw+TcACgkQ1E2HcBNypM6K1wCfcbHFP6QS6sWNfcGBRee1Fii6
    GRQAoIjnFeTiKEcJgJcI7K6Uyn9XXD3c
    =sv2g
    -----END PGP SIGNATURE-----
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Marcus Reimann at May 17, 2010 at 11:20 am
    Hi Dylan,

    my comments are inline:

    Am 17.05.2010 10:07, schrieb Dylan Schiemann:
    Also, we have this heading for each doc:

    Status: Draft
    Version: 1.0
    Project owner: Mike Wilcox, Tom Trenka
    Author: Mike Wilcox
    Available: since 1.3

    Does status correspond to the documentation or the module?

    What does the version number represent? It's likely confusing when
    comparing it to the explanation of Available.

    Project Owner and Author... is Author the author of the docs, or of the
    source code? How do I get in touch with them if there's a problem? How
    do I file a bug against the docs or the source code? (I know how, but
    why aren't we providing useful links, such as a link to known issues, a
    place to add links to known demos/tutorials, use cases, etc.? Instead,
    we're taking up a lot of screen real estate with the Documentation and
    Table of Contents navigation without offering a lot of real value there)
    Status and Version are pretty meaningless. Maybe there was a idea behind
    that, but I don't think it's necessary to use them anymore. I've
    informed Tobias some months ago, that I will delete this lines, at each
    time I will edit a page. So, in the meantime a lot of dojo/dijit pages
    shouldn't have this two lines within the head and I would recommend
    other authors to delete this lines, whenever a page is edited.

    The idea of the "Author" line is, to show the author(s) of the
    documentation page. Often there is a lot of work to do in order to
    document a component. If this were a easy task, I'm sure we would see
    much more edits from the original developers of this components.
    Therefore I think it's the right way, to honor also the author of the docs.

    The main work for developing the component was done from the "owner" of
    the component. Therefore we have started to list them as "Project owner".

    Regarding filing a bug against the docs: I remember some months ago,
    when you said, that you wouldn't like to see errors about docs within
    bugs.dojotoolkit.org (because there is already too much traffic in the
    mailbox or something like that). So, the open question is, where should
    users report errors within the docs?

    Finally, there's a lot of documentation in the source code itself at
    http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/av/FLAudio.js .
    None of this appears on the documentation page. Nor does a mechanism
    exist for the visitor to the page to view the source code of the module
    itself.
    This would be a great extension of docs. A simple mechanism to link to
    the API tool. Or to the source code. It would be also cool to have a
    simple mechanism to inlcude a placeholder within the text, which will be
    replaced with the description of the parameters of a function, right
    from the source code.
    ...

    * How do we solve some of the other fundamental problems with the docs
    that have little to do with the actual tooling choices?
    In my eyes that's the most important question. Any suggestions?

    Marcus
  • Dylan Schiemann at May 17, 2010 at 2:58 pm

    on 5/17/10 8:20 AM (GMT-07:00) Marcus Reimann said the following:
    Hi Dylan,

    my comments are inline:

    Am 17.05.2010 10:07, schrieb Dylan Schiemann:
    Also, we have this heading for each doc:

    Status: Draft
    Version: 1.0
    Project owner: Mike Wilcox, Tom Trenka
    Author: Mike Wilcox
    Available: since 1.3

    Does status correspond to the documentation or the module?

    What does the version number represent? It's likely confusing when
    comparing it to the explanation of Available.

    Project Owner and Author... is Author the author of the docs, or of the
    source code? How do I get in touch with them if there's a problem? How
    do I file a bug against the docs or the source code? (I know how, but
    why aren't we providing useful links, such as a link to known issues, a
    place to add links to known demos/tutorials, use cases, etc.? Instead,
    we're taking up a lot of screen real estate with the Documentation and
    Table of Contents navigation without offering a lot of real value there)
    Status and Version are pretty meaningless. Maybe there was a idea behind
    that, but I don't think it's necessary to use them anymore. I've
    informed Tobias some months ago, that I will delete this lines, at each
    time I will edit a page. So, in the meantime a lot of dojo/dijit pages
    shouldn't have this two lines within the head and I would recommend
    other authors to delete this lines, whenever a page is edited.
    I assumed it meant documentation status, but I think people care more
    about module status at that point. For example, for dojox projects it
    would be ideal if it included the status of the module (alpha, beta,
    etc.). Version for the docs makes no sense.
    The idea of the "Author" line is, to show the author(s) of the
    documentation page. Often there is a lot of work to do in order to
    document a component. If this were a easy task, I'm sure we would see
    much more edits from the original developers of this components.
    Therefore I think it's the right way, to honor also the author of the docs.

    The main work for developing the component was done from the "owner" of
    the component. Therefore we have started to list them as "Project owner".
    Perhaps Author should say Doc Author? Because in theory the project
    owner isn't the original creator/author of the source code for that module.
    Regarding filing a bug against the docs: I remember some months ago,
    when you said, that you wouldn't like to see errors about docs within
    bugs.dojotoolkit.org (because there is already too much traffic in the
    mailbox or something like that). So, the open question is, where should
    users report errors within the docs?
    I think my concern was that it was too heavyweight for simple fixes. My
    original suggestion was a form at the bottom of each doc page that was
    basically a way to report an issue with that page of docs, which would
    then get sent to the doc author(s) for that page, either through email
    or an issue tracking system.
    Finally, there's a lot of documentation in the source code itself at
    http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/av/FLAudio.js .
    None of this appears on the documentation page. Nor does a mechanism
    exist for the visitor to the page to view the source code of the module
    itself.
    This would be a great extension of docs. A simple mechanism to link to
    the API tool. Or to the source code. It would be also cool to have a
    simple mechanism to inlcude a placeholder within the text, which will be
    replaced with the description of the parameters of a function, right
    from the source code.
    Yes, I guess I thought that was the original goal... otherwise, what's
    the real point of the source code docs if they aren't showing up in the
    generated docs? In my example above, they instead show up at
    http://dojotoolkit.org/api/dojox/av/FLAudio.html . Cool that it's
    there, sucks that there's no integration or correlation, and thus a lot
    of wasted effort between the reference guide and API documentation.
    ...

    * How do we solve some of the other fundamental problems with the docs
    that have little to do with the actual tooling choices?
    In my eyes that's the most important question. Any suggestions?
    I feel like overall we're lacking a lot of vision, which has led to a
    lot of neglect, and this goes well beyond docs. I have some ideas on
    how to get people fired up and contributing more for 1.5. I'll send
    those to a separate thread.
    Marcus
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Sam foster at May 21, 2010 at 8:53 am
    My 2c in brief. I agree wholeheartedly with the main premise here -
    docs should be files, that can be versioned, edited directly, grep'ed
    and so on. The wiki stands between you and all that make you
    productive in a filesystem. (the same is true for all CMS). There's a
    trade-off, but I think the balance favours ReST docs as files stored
    in a VCS.

    If we want casual contributions, we (by which I mean me, if pressed)
    can make a web front-end that outputs a patch to the version edited.
    Or an AIR app, or whatever.

    /Sam
  • Marcus Reimann at May 17, 2010 at 5:02 am
    We're all very busy. That's the crux of our business.

    So, what's your plan in order to present a functional demo with showing
    the whole process - from creating a new RST file to rendering a HTML and
    PDF?

    Will we are able to test this in-depth, before we discuss this change
    further?

    Regards,
    Marcus


    Am 16.05.2010 21:22, schrieb Nikolai Onken:
    It's more a question to choose the right tool for the job.
    To me right now it is most important that we use a system which does not depend on a person knowing how it works.
    And this to me at least leads to some files using some data format (reST) and a storage system which everybody knows (svn, whatever).
    We see this happening right now - the people who know how it currently works (me included) are super busy and having a hard time freeing up time to do the work which needs to be done.

    Whether SVN nor Github is the right platform for documentation. We all
    know, how much time a checkin within a SVN costs, instead of a simple
    preview or save within a WIKI. Also getting updates is very slow with
    SVN. I don't think I will be happy to wait for a SVN checkout, in order
    to start editing, just for the sake of using SVN instead of a WIKI.
    I don't have the issues you have. Working with SVN or GIT is something I do every day and it does not slow down my work.
    Yes getting the initial checkout may take some time but the benefits of a vcs still weigh out the disadvantages.

    Furthermore, I question at which point, to which time we really need the
    files in SVN or not. The only reason for this, could be to handle the
    exported HTML pages for different Dojo versions. But this is a task at
    This is super essential. We want to be able to deliver the 1.3 docs, or 1.4 docs (at least in my opinion) as much as we want to have all the benefits of version control in general.
    Especially when having real code examples. If we can't tag doc releases how will we keep old versions?

    the end of the documentation process and would be a simple task for an
    Export Shell script. I will create this Shell script, which will do all
    the WIKI specific things, normalizing paths, copying the results to the
    right directory and/or remote servers, whenever you'll find the time to
    tell me some more details (I've already offered my support for something
    like this on several occasions to Dustin, Peter, Tobias and Nikolai).
    This is great but again does not address the issue of keeping the setup simple.
    What will happen if you will be too busy and don't have time anymore to maintain the work?

    So, no more manually steps will be necessary and the Export Shell script
    will run every night.
    To me such a process will be (as it already is) too prone to errors.

    We have already seen what happens, when tools like a forum are closed. A
    lot of users are discussing about Dojo in other forums, but not in the
    original Dojo Toolkit forum or mailing list. We will see the same with
    documentation. Or could you explain me, why users should use a SVN tool
    I think it is important to distinguish here between who we are talking to.
    With the mailing list we were changing the works of a direct interface to every dojo user and that had negative impact
    With the doc editing interface we don't (at least in my opinion). There should be one place and one place only for people wanting to check out the docs and that place is dojotoolkit.org.
    Dojocampus was always a temporary solution until the new website was done, now it is, and now we should create that clarity.

    for a short edit? If dojocampus.org/dojotoolkit.org offers no more tools
    like a WIKI, then it's only a question of time when we will see other
    WIKIs for offering this service instead.
    If we had everything based on SVN only we could open up to other editing interfaces.
    Right now we can't because the WIKI determines how everything works. If you change a file via svn and then run the wiki export it will overwrite that.
    So, in that regards moving to SVN only could be the start for such tools (as the AIR tool is) - the advantage would be that these tools will be maintained by people.
    If those people stop working on the tools the docs will still work as always. Right now as we see happening, as soon as people are getting busy the process is borken and thats bad.

    Nikolai

    Regards,
    Marcus

    --
    http://www.dojotoolkit-forum.de



    Am 13.05.2010 19:02, schrieb Nikolai Onken:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs.>2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors

    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    --
    http://www.dojotoolkit-forum.de
  • Nikolai Onken at May 17, 2010 at 9:30 am

    Will we are able to test this in-depth, before we discuss this change
    further?
    You are testing it when you are visiting http://dojotoolkit.org/reference-guide/
    The documentation there is a result of:

    1. Exporting the wiki data into normalized rest files
    2. Making sure all attachments, etc. are moved as well
    3. Putting the data into svn https://svn.dojotoolkit.org/dojo_doc_wiki/_source-moin
    4. Checking them out
    5. running "make html"

    What I want to get rid of is step 1. 2. and make step 3. an item of the person writing docs.
    So there is nothing really to test unless you need to test whether svn is working or what people say when docs on campus are not the official source anymore.
    Again to be clear, I am not proposing some kind of new way of how we handle the docs - I just want to cut some of the tooling we use because it is creating a major headache and because we have a very tight dependency on that tool which I dislike a lot.

    Cheers,

    Nikolai
    Regards,
    Marcus


    Am 16.05.2010 21:22, schrieb Nikolai Onken:
    It's more a question to choose the right tool for the job.
    To me right now it is most important that we use a system which does not depend on a person knowing how it works.
    And this to me at least leads to some files using some data format (reST) and a storage system which everybody knows (svn, whatever).
    We see this happening right now - the people who know how it currently works (me included) are super busy and having a hard time freeing up time to do the work which needs to be done.

    Whether SVN nor Github is the right platform for documentation. We all
    know, how much time a checkin within a SVN costs, instead of a simple
    preview or save within a WIKI. Also getting updates is very slow with
    SVN. I don't think I will be happy to wait for a SVN checkout, in order
    to start editing, just for the sake of using SVN instead of a WIKI.
    I don't have the issues you have. Working with SVN or GIT is something I do every day and it does not slow down my work.
    Yes getting the initial checkout may take some time but the benefits of a vcs still weigh out the disadvantages.

    Furthermore, I question at which point, to which time we really need the
    files in SVN or not. The only reason for this, could be to handle the
    exported HTML pages for different Dojo versions. But this is a task at
    This is super essential. We want to be able to deliver the 1.3 docs, or 1.4 docs (at least in my opinion) as much as we want to have all the benefits of version control in general.
    Especially when having real code examples. If we can't tag doc releases how will we keep old versions?

    the end of the documentation process and would be a simple task for an
    Export Shell script. I will create this Shell script, which will do all
    the WIKI specific things, normalizing paths, copying the results to the
    right directory and/or remote servers, whenever you'll find the time to
    tell me some more details (I've already offered my support for something
    like this on several occasions to Dustin, Peter, Tobias and Nikolai).
    This is great but again does not address the issue of keeping the setup simple.
    What will happen if you will be too busy and don't have time anymore to maintain the work?

    So, no more manually steps will be necessary and the Export Shell script
    will run every night.
    To me such a process will be (as it already is) too prone to errors.

    We have already seen what happens, when tools like a forum are closed. A
    lot of users are discussing about Dojo in other forums, but not in the
    original Dojo Toolkit forum or mailing list. We will see the same with
    documentation. Or could you explain me, why users should use a SVN tool
    I think it is important to distinguish here between who we are talking to.
    With the mailing list we were changing the works of a direct interface to every dojo user and that had negative impact
    With the doc editing interface we don't (at least in my opinion). There should be one place and one place only for people wanting to check out the docs and that place is dojotoolkit.org.
    Dojocampus was always a temporary solution until the new website was done, now it is, and now we should create that clarity.

    for a short edit? If dojocampus.org/dojotoolkit.org offers no more tools
    like a WIKI, then it's only a question of time when we will see other
    WIKIs for offering this service instead.
    If we had everything based on SVN only we could open up to other editing interfaces.
    Right now we can't because the WIKI determines how everything works. If you change a file via svn and then run the wiki export it will overwrite that.
    So, in that regards moving to SVN only could be the start for such tools (as the AIR tool is) - the advantage would be that these tools will be maintained by people.
    If those people stop working on the tools the docs will still work as always. Right now as we see happening, as soon as people are getting busy the process is borken and thats bad.

    Nikolai

    Regards,
    Marcus

    --
    http://www.dojotoolkit-forum.de



    Am 13.05.2010 19:02, schrieb Nikolai Onken:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs.>2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors

    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    --
    http://www.dojotoolkit-forum.de

    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
  • Nikolai Onken at May 17, 2010 at 9:34 am

    Will we are able to test this in-depth, before we discuss this change
    further?
    What we can do to test this is setting up for instance the nightly build of the docs and run make html every 24 hours.
    The thing though is right now that that again depends on the wiki export (which is a pain) so it won't really make sense I think to test that.

    Cheers,

    Nikolai
    Regards,
    Marcus


    Am 16.05.2010 21:22, schrieb Nikolai Onken:
    It's more a question to choose the right tool for the job.
    To me right now it is most important that we use a system which does not depend on a person knowing how it works.
    And this to me at least leads to some files using some data format (reST) and a storage system which everybody knows (svn, whatever).
    We see this happening right now - the people who know how it currently works (me included) are super busy and having a hard time freeing up time to do the work which needs to be done.

    Whether SVN nor Github is the right platform for documentation. We all
    know, how much time a checkin within a SVN costs, instead of a simple
    preview or save within a WIKI. Also getting updates is very slow with
    SVN. I don't think I will be happy to wait for a SVN checkout, in order
    to start editing, just for the sake of using SVN instead of a WIKI.
    I don't have the issues you have. Working with SVN or GIT is something I do every day and it does not slow down my work.
    Yes getting the initial checkout may take some time but the benefits of a vcs still weigh out the disadvantages.

    Furthermore, I question at which point, to which time we really need the
    files in SVN or not. The only reason for this, could be to handle the
    exported HTML pages for different Dojo versions. But this is a task at
    This is super essential. We want to be able to deliver the 1.3 docs, or 1.4 docs (at least in my opinion) as much as we want to have all the benefits of version control in general.
    Especially when having real code examples. If we can't tag doc releases how will we keep old versions?

    the end of the documentation process and would be a simple task for an
    Export Shell script. I will create this Shell script, which will do all
    the WIKI specific things, normalizing paths, copying the results to the
    right directory and/or remote servers, whenever you'll find the time to
    tell me some more details (I've already offered my support for something
    like this on several occasions to Dustin, Peter, Tobias and Nikolai).
    This is great but again does not address the issue of keeping the setup simple.
    What will happen if you will be too busy and don't have time anymore to maintain the work?

    So, no more manually steps will be necessary and the Export Shell script
    will run every night.
    To me such a process will be (as it already is) too prone to errors.

    We have already seen what happens, when tools like a forum are closed. A
    lot of users are discussing about Dojo in other forums, but not in the
    original Dojo Toolkit forum or mailing list. We will see the same with
    documentation. Or could you explain me, why users should use a SVN tool
    I think it is important to distinguish here between who we are talking to.
    With the mailing list we were changing the works of a direct interface to every dojo user and that had negative impact
    With the doc editing interface we don't (at least in my opinion). There should be one place and one place only for people wanting to check out the docs and that place is dojotoolkit.org.
    Dojocampus was always a temporary solution until the new website was done, now it is, and now we should create that clarity.

    for a short edit? If dojocampus.org/dojotoolkit.org offers no more tools
    like a WIKI, then it's only a question of time when we will see other
    WIKIs for offering this service instead.
    If we had everything based on SVN only we could open up to other editing interfaces.
    Right now we can't because the WIKI determines how everything works. If you change a file via svn and then run the wiki export it will overwrite that.
    So, in that regards moving to SVN only could be the start for such tools (as the AIR tool is) - the advantage would be that these tools will be maintained by people.
    If those people stop working on the tools the docs will still work as always. Right now as we see happening, as soon as people are getting busy the process is borken and thats bad.

    Nikolai

    Regards,
    Marcus

    --
    http://www.dojotoolkit-forum.de



    Am 13.05.2010 19:02, schrieb Nikolai Onken:
    Hi all,

    it's been taken quite some time to get the documentation to where we are now and things are still being far from ideal for everyone.
    To solve this situation I did some work in the past few days and want to propose following.
    This proposal will not be what most of us will like it to be, but please take a moment and think of it. I myself see no alternative to making the doc process simple and future proof.

    1. Kill the Wiki

    Yes this will be a hard one to crack and I know that the current format is very comfortable for some.
    Lets take following into consideration though:

    - The Wiki stores its data in a format which forces us to convert everything each time we want to commit the data to svn.
    - The Wiki itself does not allows us to connect to a vcs right away and so far no-one was able to come up with a bridge.
    - The Wiki does not allow us to upload custom files for demos, doc purposes. This imo is a very important fact especially since CDNs are not hosting data/test/image files.
    - The Wiki makes it way more complicated to tag releases, roll back to older versions or even say, hey, for Dojo 1.3 docs go here: ....

    2. Move everything to SVN (or whatever vcs you want)

    - This way we will have one channel of communication (vs.>2 now)
    - We can exactly track changes been made
    - We can tag doc releases much easier than we do now because the process is too complicated
    - We can revert doc changes
    - We finally can offer offline or even PDF downloads on a regular base

    Most importantly removing the Wiki will end up in us having a complete, streamlined, simple and logical doc process - yes, not as simple as a Wiki, but the Wiki is only one part in the currently still complicated process.

    To make the whole process simpler I have developed a simple AIR app which allows you to edit the docs and preview them pretty much instantly.
    Take a look at the video: http://static.uxebu.com/~nonken/dojo/DojoDocs.mov
    The source code can be found here: http://github.com/nonken/docwriter - feel free to fork, enhance, contribute, etc.
    Possible enhancements are:

    - Make it work/test on windows (only rewriting a shell script.
    - svn integration
    - git integration
    - API docs integration?

    I did not want to put this tool into Dojo's trunk because I think it is important that people see that there is also "life" outside of Dojos repo.
    If you think this is a problem, let me know and we can see if we can find a solution.
    You don't have to use this tool, it is not a requirement for a clear documentation process - it is there for people to make things easier, nothing more, northing less.

    3. The final doc process

    - Everything is done via svn, svn is the only channel
    - People can use the docwriter tool to make life a lot easier
    - We have (should) set up a doc access group so people don't have to be committer to write docs
    - At the same time we document clearly that doc errors can be filed as tickets in trac and that people with access can fix the errors.
    - We build up a doc team which is responsible of the quality

    This will also prevent that we will have non working examples. People will have the ability to preview the example in the same environment as the final version online on dojotoolkit.org

    4. Other issues/benefits

    - We will close docs.dojocampus.org, but will leave all pages intact and/or put up a redirect.
    - No more confusion on whether docs.dojocampus is the official doc or not. People who want the latest doc from trunk can check out the docs or we even can make a nightly doc build every night.
    - People can add custom data/image/whatever files to the documentation

    I would like to move further on this and this is the only solution I see which will be crystal clear.
    I know people love the Wiki, I think its great as well but is causing a lot of pain which a lot of people don't see (except by seeing that docs are not up to date).
    Please bear in mind that in the end we already have a team of people working on docs quite consistently. We don't really have random people dropping by and saying "hey, let me edit some docs" - look at the revision history.
    On top of that there are other successful documentation projects which have a committed team of people and which don't work with a Wiki, there are other ways.

    If you think this is not a viable solution please come forward with concrete suggestions on how we can make this process work.

    What do you think?

    Nikolai
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors

    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
    --
    http://www.dojotoolkit-forum.de

    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdojo-contributors @
categoriesdojo
postedMay 13, '10 at 1:02p
activeMay 21, '10 at 8:53a
posts24
users10
websitedojotoolkit.org

People

Translate

site design / logo © 2022 Grokbase