Beta-test the gitbook :D

Aurelie-Mutschler commented 7 years ago

Read the brand new gitbook and give us some feedbacks ! ttps://echopen.gitbooks.io/echopen_prototyping/content/

Indicative due date : June 30th, 2017

Criteria to close the issue :

Read the gitbook : https://echopen.gitbooks.io/echopen_prototyping/content/
Give us your remarks about thingss you didn't understand or ideas for improvements, by writing comments on this issue

nfilipov commented 7 years ago

Hi,

Thanks for putting together this well-detailed gitbook! Here are some comments from my first read-through:

General comment: the structure of the document is already there, but there are some discrepancies in terms of length and outline of sections. I understand that some older pages are to be taken out. Generally speaking, the format of the 'how to contribute' section is a good example of what felt easiest to read: relatively short main page, more detailed content in subsection pages). Also, I'm wondering if the Challenges section shouldn't go lower in the outline, or if the Stable version section should go up.

More detailed comments/questions per section:

Get started

getstarted/hacking_guide.md this is empty, maybe the intention is to replace it with the hacking_guide ? if so, it took me a while to figure it out.

Product backlog

in backlog/backlog.md: -- what the heck is a CapMed ? :rofl: Besides, if we're mentioning a certain meeting with its date, it would be nice to point to the minutes of said meeting, if possible. -- To clarify the read of this section, and to make it look like the other sections, I'd keep only the first paragraph and move the rest (from "Usage") to a next .md file. Justification, if needed: it looks like most of what comes next already are Technical constraints, which is the name of the next subsection ;) -- "It is not ... A per se imaging tool" did you mean standalone imaging tool ? or what else? -- B-mode is imaging jargon ;) It's nice to link a paper to describe what B-mode imaging is, but it wouldn't hurt to add something short right next to it, like "cross-sectional image" for the impatient reader, or newbies like myself :nerd_face:
in backlog/technical.md: -- in the list of mechanical parts, some are greyed out, some are bold; is it a matter of importance of the piece itself, or just a mistake ? -- this is again a matter of taste, but since the list is very long, would it make more sense to split in scanning/acoustics/powering ?

Challenges

in challenges/challenges.md: -- "You don't need to subscribe to a team to participate to challenges" This is important, is it already said higher in the document, in the 'contribute' section ?
in challenges/gpu-and-real-time-processing.md: -- A little language polishing might be in order there. I'd volunteer for it since I'm already assigned to such a task. -- I'm lost: are we using RenderScript, Vulcan ? In any event the NB should come on top. -- "Mention on our Hall of fame of open sources dudes" ... what about open source chicks ??? :woman_cartwheeling:
in challenges/scan-conversion.md: -- I read earlier in backlog/technical.md that the goal in frame-rate is 10-20 fps and achieved is 2fps... but here it says you have already achieved 90-100 fps. What am I missing? Also, sorry for the language trolling, but "Actual" should be replaced by "Current" ! -- same comments about the open source dudes ... ;)
in challenges/data-format.md: -- There are some words/sentences in french here.

In progress

in inprogress/inprogress.md: -- what's a CapTech ? :baby:
in /inprogress/requirements/preparing-captech.md, it felt like this was more of an internal document than a gitbook-like document, and so I didn't review it.
for what came next, I assumed it was too early to review, since many of the subsections only said "coming soon..."

Stable Release v3.0.0

Requirements and Specifications point to empty pages, for the moment ...
in stable/requirements/specifications/mobile-app.md: -- "... today, the frame-rate is 5 frames per second (fps)": I'm confused. Previous mentions were 2fps, then 90-100 (but only on mobile app, if I understand correctly). What is the currently achieved framerate ? Also, the last sentence, "In the current hardware configuration" is hanging without an end. -- " -> clement for more details" this could be explicited with a @ , no ?
in stable/requirements/UX_design: -- we open on an empty page again. -- it looks like this is closely related to the previous section, right ? -- images are HUGE :smile:
in stable/doc_pipeline.md: -- the words in each block are cropped, but that could also be because of my browser ...
in stable/doc_hardware.md: -- I'm not a hardware expert, so the info would probably make more sense to someone else, but it seems ok. It's actually quite clear.
in stable/doc_software.md: -- RenderScript ... I'm assuming now that what I read earlier in the Challenges section was outdated :sweat_smile:
in stable/characteristics.md: -- I understand that these things may change/have changed over time, but it's best to be consistent between all the places in the gitbook where those numbers are showcased (I'm talking about fps again :wink: )
in stable/guide_hardware.md: -- First sentence has hargon, and I'm not sure if it was necessary here. -- Some pictures (PCB, capacitors, etc.) can be resized or cropped. -- there are a few "@todo" , "@question" here and there ... -- This alone is a very long subsection. If it's fine with hardware users, OK, but what about switching between steps with arrows instead of scrolling down for ever ?

References

a few empty pages (certification, hardware, embedded systems, denoising, leaderboard, benchmark)
feels like the android app page could go up, no ?

voila

Aurelie-Mutschler commented 7 years ago

Ping @lecoued

ApollineF commented 7 years ago

Hi,

General comment : I think that when you first discover the Gitbook it's quite hard to understand where you can find an information quickly. Maybe in the first section we could add a kind of summary, or just add what is written at "How to contribute/Work method/medicotechnical gitbook/Outline. Indeed basic information about the organization of the Gitbook is written there but it's not the first thing you read and it's not very easy to find.

Remarks by section: --> How to contribute:

Work method: Is the strucure of the medicotechnical Gitbook the same as the prototyping Gitbook's ? Maybe it is but it seems a little strange to me, I wonder if there is a mistake here.
The 'Find your team' section is fine.
Maybe you should separate the contributor's guide from the working method because even if you have already read this section, you might need to use the contributor's guide a few days later. It's important to be able to find it quickly.

--> Get started It's a little frustrating to read the list of the things you need to design the echopen probe and then ... nothing. Maybe you should add a link to the next step, or just a sentence to say what to do next.

--> Product backlog

Why is there a complicated Id for each functionnality that is longer than the name ? What for ? Why are there so many question marks in the mechanics chart ?
What is the difference between Technical constrains and functionnal specifications ? Is it a Hardware/software thing ? Why is there a difference in their organizations (charts vs text, chronological order or not) ? Nevertheless, the explanations are very clear in those sections.

--> Challenges

Scan conversion : the schemes titles are written in french. Current implementation: a lot of spelling mistakes here.
data format :'The project already acquires some data on which one can work - being images or data - it would then be awesome to capitalize on this and allow those who want to do some signal processing to work on a couple of files that can be given to data processing specialists.' This is not very clear. You want some people to do some signal processing on a couple of files only and then give it to data processing specialists ? I thought that those specialists needed lots of data and not just a coupled of files. I imagine that the persons who are able to create that format will need to understand what it will be used for alittle more precisely. Thre is a sentence that is still written in french: 'Un hackaton pour une app qui exporte le format echopen en DICOM ?'

ApollineF commented 7 years ago

I'll read the rest of the GitBook tomorrow.

Aurelie-Mutschler commented 7 years ago

Thanks Apolline !! Waiting for more comments then ;)

ApollineF commented 7 years ago

Hi, I've just finished the GitBook, here are the rest of my remarks.

--> Challenges If you don't need to subscribe to a team to participate to challenges, then how do you ? It seems logical that you can try to find a solution on your own, but how do you tell the community that you've found something ? Do you need to use GitHub too ? Do you send an e-mail ? It should be written there.

Hetic school challenge : this section is empty, maybe empty sections sould not appear on the GitBook. They could be on GitHub only, waiting to be ready.

--> In progress

Preparing CapTech: what is a "Raspberry benchmarking tool" ? I've googled it and I still don't understand. The rest of this section is fine.

-->Stable release V3.0.0.0

Specifications/Mobile app: there is only a little problem with the layout in the third point.
UX Design/Mobile app : the screenshots seem pretty cool ! Where are the recquirements about the Hardware, data processing and so on ? This section is about the mobile app only.
Hardware documentation/Electronic analogic: spelling mistakes.
Software documentation/Open CV: the link towards the Starter Kit Gitbook doesn't work.
- Device characteristics --> Actually reachED. About the goal section: is ti about the goals that were fixed for this version of the device or the ones that were fixed for the final device ? I mean, you probably knew that this version wouldn't have three frequencies when the CapTech occured. It's not very clear.
  - Focal zone: spelling mistakes.
Production guide:
- Reproducing the device: "@todo AJOUTER UN SCHEMA D'ATTRIBUTION DES PISTES"
Android App: there is nothing but the dates of the meetings. Where can you find informations about them ? Could there be a link ?

--> References

Mechanical issues. The explanations are very clear, except this sentence :'Note : in order to facilitate certain medical examinations, in particular between two close ribs, it is preferable to approach as far as possible the axis of rotation of the transducer of the end of the probe tip in contact with the body.' What is the probe tip ? How do you approach as far as possible ?
Signal processing: From the Analytic to the $IQ$ representation. Spelling mistakes. Nevertheless, the signal processing section is well-organized and the explanations are clear.
Android App: What is OpenCV ? Why would you need to install it ? "Let's note that this piece of API knocks the JNI. That's the reason why in the preceding section, we invite the user to inform the ndk.dir in local.propeties file" Honestly I don't have the slightest idea of what this sentence means, but maybe it's not a problem at all. My question is: Who is supposed to read those documents ? If they are written only for future members of the team who wrote them then it's not a problem.

A few general remarks to finish: Maybe the section about the stable release should come before the "In progress" section. Indeed, the latter is about the improvements that are being made but the new reader still doesn't know what has been done. A lot of sections are still empty but I suppose that you are working on them. However, the GitBook gives a good global view of the prototype :)

Aurelie-Mutschler commented 7 years ago

I put here the synthesis of remarks from @nfilipov & @ApollineF - @ApollineF I put your name next do the points you can address by yourself ;)

Hi,

Thanks for putting together this well-detailed gitbook! Here are some comments from my first read-through:

General comment: the structure of the document is already there, but there are some discrepancies in terms of length and outline of sections. I understand that some older pages are to be taken out. Generally speaking, the format of the 'how to contribute' section is a good example of what felt easiest to read: relatively short main page, more detailed content in subsection pages). Also, I'm wondering if the Challenges section shouldn't go lower in the outline, or if the Stable version section should go up.

More detailed comments/questions per section:

Get started

getstarted/hacking_guide.md this is empty, maybe the intention is to replace it with the hacking_guide ? if so, it took me a while to figure it out.

Product backlog

in backlog/backlog.md: -- what the heck is a CapMed ? :rofl: Besides, if we're mentioning a certain meeting with its date, it would be nice to point to the minutes of said meeting, if possible. @ApollineF -- To clarify the read of this section, and to make it look like the other sections, I'd keep only the first paragraph and move the rest (from "Usage") to a next .md file. Justification, if needed: it looks like most of what comes next already are Technical constraints, which is the name of the next subsection ;) @ApollineF -- "It is not ... A per se imaging tool" did you mean standalone imaging tool ? or what else? @ApollineF -- B-mode is imaging jargon ;) It's nice to link a paper to describe what B-mode imaging is, but it wouldn't hurt to add something short right next to it, like "cross-sectional image" for the impatient reader, or newbies like myself :nerd_face: @ApollineF
in backlog/technical.md: -- in the list of mechanical parts, some are greyed out, some are bold; is it a matter of importance of the piece itself, or just a mistake ? @ApollineF you can ask @Bivi :wink: -- this is again a matter of taste, but since the list is very long, would it make more sense to split in scanning/acoustics/powering ? @ApollineF

Challenges @ApollineF you can discuss the remarks about Challenges with @clecoued and @benchoufi

in challenges/challenges.md: -- "You don't need to subscribe to a team to participate to challenges" This is important, is it already said higher in the document, in the 'contribute' section ?
in challenges/gpu-and-real-time-processing.md: -- A little language polishing might be in order there. I'd volunteer for it since I'm already assigned to such a task. -- I'm lost: are we using RenderScript, Vulcan ? In any event the NB should come on top. -- "Mention on our Hall of fame of open sources dudes" ... what about open source chicks ??? :woman_cartwheeling:
in challenges/scan-conversion.md: -- I read earlier in backlog/technical.md that the goal in frame-rate is 10-20 fps and achieved is 2fps... but here it says you have already achieved 90-100 fps. What am I missing? Also, sorry for the language trolling, but "Actual" should be replaced by "Current" ! -- same comments about the open source dudes ... ;)
in challenges/data-format.md: -- There are some words/sentences in french here.

In progress

in inprogress/inprogress.md: -- what's a CapTech ? :baby:
in /inprogress/requirements/preparing-captech.md, it felt like this was more of an internal document than a gitbook-like document, and so I didn't review it.
for what came next, I assumed it was too early to review, since many of the subsections only said "coming soon..."

Stable Release v3.0.0

Requirements and Specifications point to empty pages, for the moment ... @ApollineF
in stable/requirements/specifications/mobile-app.md: -- "... today, the frame-rate is 5 frames per second (fps)": I'm confused. Previous mentions were 2fps, then 90-100 (but only on mobile app, if I understand correctly). What is the currently achieved framerate ? Also, the last sentence, "In the current hardware configuration" is hanging without an end. -- " -> clement for more details" this could be explicited with a @ , no ? @ApollineF
in stable/requirements/UX_design: -- we open on an empty page again. @ApollineF -- it looks like this is closely related to the previous section, right ? -- images are HUGE :smile: @ApollineF
in stable/doc_pipeline.md: -- the words in each block are cropped, but that could also be because of my browser ... @ApollineF
in stable/doc_hardware.md: -- I'm not a hardware expert, so the info would probably make more sense to someone else, but it seems ok. It's actually quite clear.
in stable/doc_software.md: -- RenderScript ... I'm assuming now that what I read earlier in the Challenges section was outdated :sweat_smile:
in stable/characteristics.md: -- I understand that these things may change/have changed over time, but it's best to be consistent between all the places in the gitbook where those numbers are showcased (I'm talking about fps again :wink: )
in stable/guide_hardware.md: -- First sentence has jargon, and I'm not sure if it was necessary here. -- Some pictures (PCB, capacitors, etc.) can be resized or cropped. -- there are a few "@todo" , "@question" here and there ... -- This alone is a very long subsection. If it's fine with hardware users, OK, but what about switching between steps with arrows instead of scrolling down for ever ?

References

a few empty pages (certification, hardware, embedded systems, denoising, leaderboard, benchmark) @ApollineF
feels like the android app page could go up, no ?

General comment : I think that when you first discover the Gitbook it's quite hard to understand where you can find an information quickly. Maybe in the first section we could add a kind of summary, or just add what is written at "How to contribute/Work method/medicotechnical gitbook/Outline. Indeed basic information about the organization of the Gitbook is written there but it's not the first thing you read and it's not very easy to find. @ApollineF

Remarks by section: --> How to contribute:

Work method: Is the strucure of the medicotechnical Gitbook the same as the prototyping Gitbook's ? Maybe it is but it seems a little strange to me, I wonder if there is a mistake here. @ApollineF The 'Find your team' section is fine. Maybe you should separate the contributor's guide from the working method because even if you have already read this section, you might need to use the contributor's guide a few days later. It's important to be able to find it quickly. @ApollineF --> Get started It's a little frustrating to read the list of the things you need to design the echopen probe and then ... nothing. Maybe you should add a link to the next step, or just a sentence to say what to do next.

--> Product backlog

Why is there a complicated Id for each functionnality that is longer than the name ? What for ? Why are there so many question marks in the mechanics chart ? @ApollineF you can discuss that with @Bivi What is the difference between Technical constrains and functionnal specifications ? Is it a Hardware/software thing ? Why is there a difference in their organizations (charts vs text, chronological order or not) ? Nevertheless, the explanations are very clear in those sections.

--> Challenges @ApollineF you can discuss Challenges with @clecoued and @benchoufi

Scan conversion : the schemes titles are written in french. Current implementation: a lot of spelling mistakes here. data format :'The project already acquires some data on which one can work - being images or data - it would then be awesome to capitalize on this and allow those who want to do some signal processing to work on a couple of files that can be given to data processing specialists.' This is not very clear. You want some people to do some signal processing on a couple of files only and then give it to data processing specialists ? I thought that those specialists needed lots of data and not just a coupled of files. I imagine that the persons who are able to create that format will need to understand what it will be used for alittle more precisely. Thre is a sentence that is still written in french: 'Un hackaton pour une app qui exporte le format echopen en DICOM ?'

--> Challenges If you don't need to subscribe to a team to participate to challenges, then how do you ? It seems logical that you can try to find a solution on your own, but how do you tell the community that you've found something ? Do you need to use GitHub too ? Do you send an e-mail ? It should be written there.

Hetic school challenge : this section is empty, maybe empty sections should not appear on the GitBook. They could be on GitHub only, waiting to be ready.

--> In progress

Preparing CapTech: what is a "Raspberry benchmarking tool" ? I've googled it and I still don't understand. The rest of this section is fine.

-->Stable release V3.0.0.0

Specifications/Mobile app: there is only a little problem with the layout in the third point. UX Design/Mobile app : the screenshots seem pretty cool ! Where are the requirements about the Hardware, data processing and so on ? This section is about the mobile app only. Hardware documentation/Electronic analogic: spelling mistakes. @ApollineF Software documentation/Open CV: the link towards the Starter Kit Gitbook doesn't work. @ApollineF

Device characteristics --> Actually reachED. About the goal section: is ti about the goals that were fixed for this version of the device or the ones that were fixed for the final device ? I mean, you probably knew that this version wouldn't have three frequencies when the CapTech occured. It's not very clear. @ApollineF
Focal zone: spelling mistakes. @ApollineF

Production guide:

Reproducing the device: "@todo AJOUTER UN SCHEMA D'ATTRIBUTION DES PISTES" Android App: there is nothing but the dates of the meetings. Where can you find informations about them ? Could there be a link ?

--> References

Mechanical issues. The explanations are very clear, except this sentence :'Note : in order to facilitate certain medical examinations, in particular between two close ribs, it is preferable to approach as far as possible the axis of rotation of the transducer of the end of the probe tip in contact with the body.' What is the probe tip ? How do you approach as far as possible ? @ApollineF you can discuss that with @Bivi

Signal processing: From the Analytic to the $IQ$ representation. Spelling mistakes. Nevertheless, the signal processing section is well-organized and the explanations are clear.

Android App: What is OpenCV ? Why would you need to install it ? "Let's note that this piece of API knocks the JNI. That's the reason why in the preceding section, we invite the user to inform the ndk.dir in local.propeties file" Honestly I don't have the slightest idea of what this sentence means, but maybe it's not a problem at all. My question is: Who is supposed to read those documents ? If they are written only for future members of the team who wrote them then it's not a problem. @ApollineF you can discuss that with @clecoued and @benchoufi

A few general remarks to finish: Maybe the section about the stable release should come before the "In progress" section. Indeed, the latter is about the improvements that are being made but the new reader still doesn't know what has been done. @ApollineF A lot of sections are still empty but I suppose that you are working on them. However, the GitBook gives a good global view of the prototype :)

Aurelie-Mutschler commented 7 years ago

I'll handle remaining comments

hackolite commented 7 years ago

is it possible to download this book as a pdf ebook ?

hackolite commented 7 years ago

dead link : https://echopen.gitbooks.io/starterkit/content/intro.md/readme.html https://echopen.gitbooks.io/echopen_prototyping/content/inprogress/backlog/technical.md

Aurelie-Mutschler commented 7 years ago

@hackolite now you can download the PDF 😉 not sure if the page layout will be beautiful, but still, it's possible !

echopen / echopen_prototyping

Beta-test the gitbook :D #64