Documentation about angularjs-genoverse HOT 6 CLOSED

Hopefully that'll be fine for now. Thanks.

from angularjs-genoverse.

Hi, Simon!

Sorry, if I caused any problems, had best intentions.

Do you want me to remove those links or point to the main repo, as soon as docs are there? No problem, I'll do as you say. Are there any legal issues or anything?

In my opinion, though, documentation you created is of very high quality and incredibly helpful, it is really missing from the main WTSI Genoverse repo. It's just my humble opinion, but, as Github motto says, 'ship early-ship often' - imperfect documentation with some minor flaws, served early, is better than none. And it's also ok to re-write it, introducing dramatic changes - but why not publish first version first? Look at the docs of webpack or react-router or angular's ui-router - they're "always never the same".

https://shipitsquirrel.github.io/images/ship%20it%20squirrel.png

They actually ask once in a while about Genoverse and I point them to you, for instance Sam Griffiths-Jones, author of miRBase, was really interested lately. I think, he would really appreciate it, if you published these docs.

from angularjs-genoverse.

The problem with that documentation as is stands is that it is incomplete and [probably] out of date, and I haven't had time to do the work needed to finish it. I generally prefer to get things right, rather than release something that I don't think is ready ;-)

I'm also concerned that linking to my repo will confuse people, who I think would be quite likely to go from the docs to look at the code, which is hugely behind the main repo.

from angularjs-genoverse.

I see.

I always preferred to get things done right first, too, but at some point realised, this was making me hugely unproductive.

Perfecting the documentation in one long jump is like jumping over a chasm - this is a task that will take a big chunk of time and in the middle of it the project is essentially broken - cause undocumented browser isn't really usable for someone like Sam, who wants it.

I figured that for me long jumps don't work - it's psychologically tempting to postpone long jump tasks, cause you're not getting those immediate dopamine shots as a psychological reward, as with continuous granular improvement. And also managers really don't like when I say "I need to do long jump, see you in 3 weeks". Moreover, if in the middle of a long jump something distracts me, I feel overwhelmed. This creates tension and anxiety.

I found out that I became more productive, when started avoiding long jumps at all costs, unless they are absolutely necessary. If I look at the tree of subtasks of a large task (e.g. large task is "write the perfect documentation"), it's easier for me to start small and work in continuous iterations. E.g. I first create the most essential piece of docs - e.g. basic use case - ship it, then start going section-by-section in a rough quality - ship it, then start improving most valuable sections - ship it, then improve the rest - ship them one by one.

Every time I ship, I feel good about myself - I improved something - my brain gets a dopamine shot and I'm more eager to continue this work next day instead of procrastinating. I can also pause the work at any point for indefinite period of time and switch to something urgent, cause at any point the project is somewhat functional, more or less. And managers are happy.

So, shipping early and often works for me. I can't imagine any sane person, who'd blame you for providing imperfect/partially obsolete documentation instead of providing none. Even if anyone's unhappy, you know, you're doing everything right.

On a more practical note: what action should I take? Shall I create warnings near links to your documentation, saying that this fork of Genoverse has the best docs available at this point, but obsolete code?

from angularjs-genoverse.

Re action: yes, please do what you have suggested, thanks.

Re long/short jumps: I do agree to a point, although if you have users who dislike change (i.e., all users!) repeatedly changing an interface over a short period of time would be detrimental to their experience of the product. The real problem I have with the documentation at this point is that Genoverse is basically a side project for me, which I occasionally get to work on as part of my main job, but the time taken to get back into the headspace where I could start writing more docs is practically a long jump by itself! (Also, pretty much all of the work I've been doing recently is impossible to break up into smaller shippable chunks, since it has involved rewriting whole interfaces and all the bits of the interface have to work at the same time).

I will think about publishing the documentation in its current format in the near future, because you're right - thinking about how much more there is to do is stressful enough that I've been ignoring it for almost a year now...

from angularjs-genoverse.

Simon, I've added warnings to the documentation page, as we agreed: https://github.com/RNAcentral/angularjs-genoverse/blob/master/README.md. If you'd like them to look any different, tell me or just fork it, change it and send me a PR.

Totally understand what you're saying about part-time, headspace and expensive context switch and no way to break the work into smaller chunks. Maybe then it's worth publishing current docs indeed. Oh, BTW, thank you for getting Genoverse this far.

from angularjs-genoverse.