About the project goal

[magnus-engstrom]

I'm (very) new to this project, and interested in learning more about the application and the current development process.

Is there any documentation that I can catch up with, like an backlog or a SDD? Or is there someone who can make the time to brief me over Skype or email?

[mounte]

I have had the opportunity to talk to Joakim and he explained alot for me. He sent me some sketches and ideas as well. I too would like to build some structure since I havent seen backlogs nor SDD's. Maybe the github-wiki is a good place to start the documentation (I have suggested using Confluence, JIra and HipChat in the future).

And maybe the documentation and specs could be a living document which evolves from questions that I, @mageng and all other in the team might have. When the answers get in there that is...

Also for the rest-api I think we could document it using https://github.com/pksunkara/alpaca or similar.

[joakimbengtson]

@mageng, you can call me anytime, or text/mail me and I call you back. Mobile: +46703489493, Skype: joakimbengtson

I will start with a short description (Github Wiki) of our thoughts of how the final product will work/look/feel. Im also in the process of describing the product for future customers in the form of a web page, this is for making the vision of the product clear to the team and make everyone work in the same direction (and to start improving the vision...)

[joakimbengtson]

Now there is a description in the client wiki. https://github.com/bookio/client/wiki/Introduction-to-the-client-from-a-user-perspective

Please read and feedback to me. I will continue to describe the product and thoughts for the future, but this should work as short introduction?

[joakimbengtson]

You can also find some sketches and ideas in Cacoo (https://cacoo.com/diagrams/1YMHGARTs2lx4636).

[javidgon]

I'd recommend to have the technical documentation (API definition, installation steps, deployment caveats...) in a folder inside the repository instead than in the Github Wiki. This easy out things in my opinion knowing that the Wiki is another repository and adds some overhead if you just want to search something fast.

Of course the rest of the documentation can be in the Wiki, it's a good place for it :smiley:

[magnus-engstrom]

@joakimbengtson, thanks for starting up the wiki. It helps alot. Good work with getting this of the ground! I'm still inclined to talk to you about the project. I will add you to Skype and make contact within a few days.

@mounte, @javidgon, I'm all with you with setting up documentation for the API. I've been using Alpaca for some applications and had good results with it. But as of late I would prefer using https://github.com/Pajk/apipie-rails and putting the API documentation generation within the resources (and thereby making it harder to miss updating the documentation along with the application).

[joakimbengtson]

I think we can let the wiki be the place for describing the project from the users perspective. Like building a manual for how the system is used. So someone new can understand what we are building. (The future "fake" home page will also help in this aspect).

And I also think its good to have the more technical doc in a separate place. What is github standard procedure? To have this in README or as @javidgon suggests docs in a separate folder?

[javidgon]

@joakimbengtson As I see it, the README file should contain a global overview of the docs, with some basic information about the "architecture" (regarding interactions with other services), "infrastructure" (if applicable), "goal of the project", "installation steps", "milestones" and "TODOs". Diagrams are very welcome, as they easy out the understanding. Of course each of these sections could contain a link pointing out to the extended version (see docs folder suggestion below)

The rest, as I said, could be placed in a separated folder inside the repo (docs folder maybe?)

[joakimbengtson]

@javidgon, So if you look at readme now (under client) I have made a chapter on localization. This should be a link to a document in folders 'docs' instead?

[javidgon]

It's a matter of taste of course, but I'd say yes. This way we don't have a long README file, and at the same time we know perfectly where to find further info about it.

[joakimbengtson]

Removed localization from readme and added new file in folder docs. (With a pointer from the read me)

Close this issue?