search

alan-if / alan-docs

Alan IF Documentation Project
https://git.io/alan-docs
Other
4 stars 0 forks source link

TBDs in App. G: Keep or Comment Out? #25

Closed tajmone closed 4 years ago

tajmone commented 6 years ago

@thoni56, in Appendix G: Localization there are three sections which have a title but then a "TBD" note instead of section contents:

Comment Out TBDs?

Shouldn't we comment them (title and all) out so that they don't show up in the actual document but only in the AsciiDoc source? or would you rather keep them visible for some reason.

Create Issues to Tracks TODOs

Also, I'll be creating an Issue for each one of them, just to keep the project's TODOs organized, regardless of who and when they get actaully written (they are pending tasks after all, so they deserve an Issue so that they can show up in the projects' dashboard).

Then, assigning these TODO Issues to one of us would be also be a good idea (again, to keep track of who will be doing what).

I could have a go at G.3. Player words, which I think I can handle, but the other two's scope is beyond my competence, so I'd assign them to you (again, no deadline attached).

Do you agree on this approach? I.e. is it OK if I just assign to you those tasks which I think need to be done and which are beyond my competence? Instead of nagging you with messages, when something is not urgent assigning it to you should be enough, then it will show up when you query open issues using asignment filters. For the urgent staff I can always nag you with the @thoni56 bell ringer :wink:.

None of these are blocking issues in regards to publishing the new Manual version as an official replacement of the original ODT/PDF — these TBDs have been there for a while anyhow, but commenting them out in the source might make the final doc look better.

As you might have noticed, in these days I've cleaned up the various loose Issues and started to use the Project dashboard to organize the various subproject of this repository, so that the various tasks are easy to track. I've also enabled some of the automatic features of the dashboard that keep track of Issues references in commits to automatically update the dashboard.

These features are quite cool and make it easier to work collaboratively, especially on the long term.

thoni56 commented 5 years ago

One argument for keeping these headings would be to make it clearer which things can be localized. But then we should probably at least say something more, a single sentence perhaps, about each of them.

tajmone commented 5 years ago

I agree. When the Manual for the beta7 will be released, if they are still empty we should comment them out (the beta7 being the first official release of the new AsciiDoc port of the Manual).

thoni56 commented 4 years ago

I did some small updates of "Word Order" and then decided to keep the TBDs. You have created issues for them, but I think they might serve as an indication to interested readers that there is more info coming, which might make them contact us, which in turn would give us more info on what they wanted to know ;-)

As I have indicated in other comments, I think we should provide what we can to the readers, but it is not a book that we will publish, but a continuously improving manual, so I'll keep the TBDs.